|
| 1 | +# Booster - fast and secure initramfs generator |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +Initramfs is a specially crafted small root filesystem that mounted at the early stages of Linux OS boot process. |
| 6 | +This initramfs among other things is responsible for unlocking encrypted partitions and mounting it as a root filesystem. |
| 7 | + |
| 8 | +Booster is a tool to create such early boot images. Booster is made with speed and full disk encryption use-case in mind. |
| 9 | + |
| 10 | +Booster advantages: |
| 11 | + * Fast image build time and fast boot time. |
| 12 | + * Out-of-box support for full disk encryption setup. |
| 13 | + * [Clevis](https://github.com/latchset/clevis/) style data binding. The encrypted filesystem can be bound |
| 14 | + to TPM2 chip or to a network service. This helps to unlock the drive automatically but only if the TPM2/network service |
| 15 | + presents. |
| 16 | + * Easy to configure. |
| 17 | + * Automatic host configuration discovery. This helps to create minimalistic images specific for the current host. |
| 18 | + |
| 19 | +There are other initramfs generators similar to booster: [mkinitcpio](https://git.archlinux.org/mkinitcpio.git/) and [dracut](https://dracut.wiki.kernel.org/index.php/Main_Page). |
| 20 | + |
| 21 | +### Install |
| 22 | +#### Arch Linux |
| 23 | +Install [booster-git](https://aur.archlinux.org/packages/booster-git/) package from AUR. |
| 24 | + |
| 25 | +At the installation time this package will create a number of booster images in your `/boot/` directory: |
| 26 | +```shell |
| 27 | +$ ls -lh /boot/booster-*.img |
| 28 | +-rwxr-xr-x 1 root root 3.9M Dec 10 20:51 /boot/booster-linux.img |
| 29 | +``` |
| 30 | + |
| 31 | +Or optionally the image can be generated manually as `booster -o mybooster.img`. Note that by default booster generates |
| 32 | +host specific images with minimum binaries needed for the current host. Providing `-universal` flag to `booster` tool |
| 33 | +will add more modules and tools and the result image will be bigger. |
| 34 | + |
| 35 | +Once the image is generated it is time to configure the bootloader. |
| 36 | + |
| 37 | +#### systemd-boot |
| 38 | +Here is a sample entry for `systemd-boot` UEFI bootloader: |
| 39 | + |
| 40 | +``` |
| 41 | +$ cat /boot/loader/entries/booster.conf |
| 42 | +title Linux with Booster |
| 43 | +linux /vmlinuz-linux |
| 44 | +initrd /intel-ucode.img |
| 45 | +initrd /booster-linux.img |
| 46 | +options rd.luks.uuid=e122d09e-87a9-4b35-83f7-2592ef40cefa root=UUID=08684949-bcbb-47bb-1c17-089aaa59e17e rw |
| 47 | +``` |
| 48 | + |
| 49 | +where `e122d09e-87a9-4b35-83f7-2592ef40cefa` is a UUID for the LUKS partition and `08684949-bcbb-47bb-1c17-089aaa59e17e` is |
| 50 | +a UUID for the encrypted filesystem (e.g. ext4). Please refer for your bootloader documentation for more info about its |
| 51 | +configuration. |
| 52 | + |
| 53 | +### Configure |
| 54 | +Booster generator has a number of configurable options. |
| 55 | + |
| 56 | +#### Config file |
| 57 | +First there is a configuration file located at `/etc/booster.yaml`. It has following fields: |
| 58 | + |
| 59 | +```yaml |
| 60 | +network: |
| 61 | + dhcp: on |
| 62 | + ip: 10.0.2.15/24 |
| 63 | + gateway: 10.0.2.255 |
| 64 | +universal: false |
| 65 | +modules: nvidia,kernel/sound/usb/ |
| 66 | +``` |
| 67 | +
|
| 68 | +`network` node, if presents, initializes network at the boot time. It is needed if mounting a root fs requires access to the network (e.g. in case of Tang binding). |
| 69 | +The address can be configured with a static ip (node `ip`) or with DHCPv4 (`dhcp: on`). |
| 70 | + |
| 71 | +`universal` is a boolean flag that tells booster to generate a universal image. |
| 72 | +By default `booster` generates a host-specific image that includes kernel modules used at the *current host*. |
| 73 | +For example if the host does not have a TPM2 chip then tpm modules are ignored. |
| 74 | +*Universal* image includes many kernel modules and tools that might be needed at a broad range of hardware configurations. |
| 75 | + |
| 76 | +`modules` is a comma-separates list of extra modules to add to the generated image. One can use a module name or a path relative |
| 77 | +to the modules dir (`/usr/lib/modules/$KERNEL_VERSION`). If the path ends with slash symbol (`/`) then it considered a directory |
| 78 | +and all modules from this directory needs to be added recursively. `booster` also takes modules dependencies into account, all dependencies |
| 79 | +of the specified modules will be added to the image as well. |
| 80 | + |
| 81 | +#### Command-line arguments |
| 82 | +`booster` accepts a list of arguments: |
| 83 | + * `-universal` generate a universal image |
| 84 | + * `-kernelVersion` use modules for the given kernel version. If the flag is not specified then the current kernel is used (as reported by `uname -r`). |
| 85 | + * `-output` output file, by default `booster.img` used |
| 86 | + * `-force` overwrite output file if it exists |
| 87 | + |
| 88 | +#### Kernel boot parameter |
| 89 | +Some parts of booster boot functionality can be modified with kernel boot parameters. These parameters are usually set through bootloader config. |
| 90 | +Booster boot uses following kernel parameters: |
| 91 | + * `booster.debug=1` enable booster debug output. It is printed to console at the boot time. This feature might be useful to debug booster issues. |
| 92 | + * `root=($PATH|UUID=$UUID)` root device |
| 93 | + * `rd.luks.uuid=$UUID` UUID of the LUKS partition where the root partition is enclosed. booster will try to unlock this LUKS device. |
| 94 | + * `rd.luks.name=$UUID:$NAME` similar to `rd.luks.uuid` parameter but also specifies the name used for the LUKS device opening. |
| 95 | + * `fstype=type` booster will try to detect root filesystem type. But if the autodetection does not work then this kernel parameter is be useful. |
| 96 | + Also please file a ticket so we can improve the code that detects filetypes. |
| 97 | + |
| 98 | +### Build |
| 99 | +The project consists of 3 components: |
| 100 | + * `init` binary that runs as a part of your machine boot process. It is going to be the very first user process run at your machine. |
| 101 | + * `generator` tool that creates ramfs image with all components needed to boot the computer |
| 102 | + * `integration_tests` tests that involve all components and use QEMU to boot from a generated image |
| 103 | + |
| 104 | +These components use standard Golang tooling. To build any part do `go build`, to run tests do `go test`. |
| 105 | + |
| 106 | +### Run tests |
| 107 | + ```bash |
| 108 | +cd {init,generator,integration_tests} |
| 109 | +go test -v |
| 110 | + ``` |
| 111 | + |
| 112 | +### Debugging |
| 113 | +If you have a problem with booster boot tool you can enable debug mode to get more |
| 114 | +information about what is going on. Just add `booster.debug=1` kernel parameter and booster |
| 115 | +provide additional logs. |
| 116 | + |
| 117 | +### Credits |
| 118 | +Work on this project has been started as a part of Twitter's hack week. Huge thanks to my employer for its support |
| 119 | +of open-source development. Special thanks to [Ian Brown](https://twitter.com/igb). |
| 120 | + |
| 121 | +Booster architecture has been inspired by Michael Stapelberg's project called [distri](https://distr1.org/). |
| 122 | +Initial version of booster borrowed a lot of ideas from the distri's initramfs generator. |
| 123 | + |
| 124 | +### Licence |
| 125 | +See [license](LICENSE) |
0 commit comments