Skip to content

Commit b103fda

Browse files
azenlaazenla
committed
chore(docs): add debian setup guide
1 parent 7be42ba commit b103fda

3 files changed

Lines changed: 150 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ We recommend running Sprout without Secure Boot for development, and with Secure
4848
| Operating System | Secure Boot Enabled | Link |
4949
|------------------|---------------------|-------------------------------------------------------|
5050
| Ubuntu | ✅ | [Setup Guide](./docs/setup/signed/ubuntu.md) |
51+
| Debian | ✅ | [Setup Guide](./docs/setup/signed/debian.md) |
5152
| Fedora | ❌ | [Setup Guide](./docs/setup/unsigned/fedora.md) |
5253
| Alpine Edge | ❌ | [Setup Guide](./docs/setup/unsigned/alpine-edge.md) |
5354
| Generic Linux | ❌ | [Setup Guide](./docs/setup/unsigned/generic-linux.md) |

‎docs/setup/signed/debian.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Setup Sprout for Debian with Secure Boot
2+
3+
## Prerequisites
4+
5+
- Modern Debian release: tested on Debian 13 ARM64
6+
- EFI System Partition mounted on `/boot/efi` (the default)
7+
- ext4 or FAT32/exFAT formatted `/boot` partition
8+
- You will need the following packages installed: `openssl`, `shim-signed`, `mokutil`, `sbsigntool`
9+
10+
## Step 1: Generate and Install Secure Boot Key
11+
12+
```bash
13+
# Create a directory to store the Secure Boot MOK key and certificates.
14+
$ mkdir -p /etc/sprout/secure-boot
15+
# Change to the created directory.
16+
$ cd /etc/sprout/secure-boot
17+
# Generate a MOK key and certificate.
18+
$ openssl req \
19+
-newkey rsa:4096 -nodes -keyout mok.key \
20+
-new -x509 -sha256 -days 3650 -subj '/CN=Sprout Secure Boot/' \
21+
-out mok.crt
22+
# Generate a DER encoded certificate for enrollment.
23+
$ openssl x509 -outform DER -in mok.crt -out mok.cer
24+
# Import the certificate into the Secure Boot environment.
25+
# This will ask you to make a password that will be used during enrollment.
26+
$ mokutil --import mok.cer
27+
# Reboot your machine.
28+
# During boot, MOK enrollment should appear. If it doesn't, ensure you are booting into the shim.
29+
# Press any key to begin MOK management. Select "Enroll MOK".
30+
# Select "View key 0", and ensure the subject says "CN=Sprout Secure Boot".
31+
# If the subject does not match, something has gone wrong with MOK enrollment.
32+
# Press Enter to continue, then select the "Continue" option.
33+
# When it asks to enroll the key, select the "Yes" option.
34+
# Enter the password that you created during the mokutil --import step.
35+
# Select "Reboot" to boot back into your Operating System.
36+
```
37+
38+
## Step 2: Prepare the Secure Boot Environment
39+
40+
```bash
41+
# Create a directory for Sprout EFI artifacts.
42+
$ mkdir -p /boot/efi/EFI/sprout
43+
44+
# For x86_64, copy the following artifacts to the Sprout EFI directory.
45+
$ cp /usr/lib/shim/shimx64.efi.signed /boot/efi/EFI/sprout/shimx64.efi
46+
$ cp /usr/lib/shim/mmx64.efi.signed /boot/efi/EFI/sprout/mmx64.efi
47+
$ cp /usr/lib/shim/fbx64.efi.signed /boot/efi/EFI/sprout/fbx64.efi
48+
49+
# For aarch64, copy the following artifacts to the Sprout EFI directory.
50+
$ cp /usr/lib/shim/shimaa64.efi.signed /boot/efi/EFI/sprout/shimaa64.efi
51+
$ cp /usr/lib/shim/mmaa64.efi.signed /boot/efi/EFI/sprout/mmaa64.efi
52+
$ cp /usr/lib/shim/fbaa64.efi.signed /boot/efi/EFI/sprout/fbaa64.efi
53+
```
54+
55+
## Step 3: Install Unsigned Sprout
56+
57+
Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
58+
For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM64 systems, download the `sprout-aarch64.efi` file.
59+
Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.efi` on your EFI System Partition.
60+
61+
## Step 4: Sign Sprout for Secure Boot
62+
63+
```bash
64+
# For x86_64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call.
65+
$ sbsign \
66+
--key /etc/sprout/secure-boot/mok.key \
67+
--cert /etc/sprout/secure-boot/mok.crt \
68+
--output /boot/efi/EFI/sprout/grubx64.efi \
69+
/boot/efi/EFI/sprout/sprout.unsigned.efi
70+
71+
# For aarch64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call.
72+
$ sbsign \
73+
--key /etc/sprout/secure-boot/mok.key \
74+
--cert /etc/sprout/secure-boot/mok.crt \
75+
--output /boot/efi/EFI/sprout/grubaa64.efi \
76+
/boot/efi/EFI/sprout/sprout.unsigned.efi
77+
```
78+
79+
## Step 5: Install and Sign EFI Drivers
80+
81+
You will need a filesystem EFI driver if `/boot` is not FAT32 or ExFAT.
82+
If `/boot` is FAT32 or ExFAT, you can skip this step.
83+
84+
Most Debian systems use an ext4 filesystem for `/boot`.
85+
You can download an EFI filesystem driver from [EfiFs releases](https://github.com/pbatard/EfiFs/releases).
86+
For ext4, download the `ext2` file for your platform. It should work for ext4 filesystems too.
87+
88+
If you have an EFI driver, copy the driver to `/boot/efi/EFI/sprout/DRIVER_NAME.unsigned.efi` for signing.
89+
90+
For example, the `ext4` driver, copy the `ext4.efi` file to `/boot/efi/EFI/sprout/ext4.unsigned.efi`.
91+
92+
Then sign the driver with the Sprout Secure Boot key:
93+
94+
```bash
95+
# Sign the ext4 driver at ext4.unsigned.efi, placing it at ext4.efi, which will be used in the configuration.
96+
$ sbsign \
97+
--key /etc/sprout/secure-boot/mok.key \
98+
--cert /etc/sprout/secure-boot/mok.crt \
99+
--output /boot/efi/EFI/sprout/ext4.efi \
100+
/boot/efi/EFI/sprout/ext4.unsigned.efi
101+
```
102+
103+
## Step 6: Create Sprout Configuration
104+
105+
Write the following to the file `/boot/efi/sprout.toml`:
106+
107+
```toml
108+
# sprout configuration: version 1
109+
version = 1
110+
111+
# global values.
112+
[values]
113+
# your linux kernel command line.
114+
linux-options = "root=UUID=MY_ROOT_UUID"
115+
116+
# load an ext4 EFI driver.
117+
# skip this if you do not have a filesystem driver.
118+
# if your filesystem driver is not named ext4, change accordingly.
119+
[drivers.ext4]
120+
path = "\\EFI\\sprout\\ext4.efi"
121+
122+
# global options.
123+
[options]
124+
# enable autoconfiguration by detecting bls enabled
125+
# filesystems and generating boot entries for them.
126+
autoconfigure = true
127+
```
128+
129+
Ensure you add the signed driver paths to the configuration, not the unsigned ones.
130+
If you do not have any drivers, exclude the drivers section entirely.
131+
132+
## Step 7: Configure Sprout Boot Entry
133+
134+
In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
135+
136+
```bash
137+
# For x86_64, run this command to add Sprout as the default boot entry.
138+
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
139+
140+
# For aarch64, run this command to add Sprout as the default boot entry.
141+
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
142+
```
143+
144+
Reboot your machine and it should boot into Sprout.
145+
If Sprout fails to boot, it should boot into the original bootloader.

‎docs/setup/signed/ubuntu.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,17 @@
22

33
## Prerequisites
44

5-
- Modern Ubuntu release: tested on Ubuntu 25.10 on ARM64
5+
- Modern Ubuntu release: tested on Ubuntu 25.10 ARM64
66
- EFI System Partition mounted on `/boot/efi` (the default)
77
- ext4 or FAT32/exFAT formatted `/boot` partition
88

99
## Step 1: Generate and Install Secure Boot Key
1010

1111
```bash
1212
# Create a directory to store the Secure Boot MOK key and certificates.
13-
mkdir -p /etc/sprout/secure-boot
13+
$ mkdir -p /etc/sprout/secure-boot
1414
# Change to the created directory.
15-
cd /etc/sprout/secure-boot
15+
$ cd /etc/sprout/secure-boot
1616
# Generate a MOK key and certificate.
1717
$ openssl req \
1818
-newkey rsa:4096 -nodes -keyout mok.key \
@@ -113,7 +113,7 @@ version = 1
113113
linux-options = "root=UUID=MY_ROOT_UUID"
114114

115115
# load an ext4 EFI driver.
116-
# skip this if you do not have an filesystem driver.
116+
# skip this if you do not have a filesystem driver.
117117
# if your filesystem driver is not named ext4, change accordingly.
118118
[drivers.ext4]
119119
path = "\\EFI\\sprout\\ext4.efi"

0 commit comments

Comments
 (0)