Skip to content

Commit 0fb54a9

Browse files
azenlaazenla
committed
chore(doc): add fedora setup guide and tweak existing guides
1 parent c4475ad commit 0fb54a9

File tree

5 files changed

+194
-13
lines changed

5 files changed

+194
-13
lines changed

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,9 @@ We recommend running Sprout without Secure Boot for development, and with Secure
4747

4848
| Operating System | Secure Boot Enabled | Link |
4949
|------------------|---------------------|-------------------------------------------------------|
50-
| Ubuntu | ✅ | [Setup Guide](./docs/setup/signed/ubuntu.md) |
50+
| Fedora | ✅ | [Setup Guide](./docs/setup/signed/fedora.md) |
5151
| Debian | ✅ | [Setup Guide](./docs/setup/signed/debian.md) |
52+
| Ubuntu | ✅ | [Setup Guide](./docs/setup/signed/ubuntu.md) |
5253
| openSUSE | ✅ | [Setup Guide](./docs/setup/signed/opensuse.md) |
5354
| Fedora | ❌ | [Setup Guide](./docs/setup/unsigned/fedora.md) |
5455
| Alpine Edge | ❌ | [Setup Guide](./docs/setup/unsigned/alpine-edge.md) |

‎docs/setup/signed/debian.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -120,8 +120,8 @@ path = "\\EFI\\sprout\\ext4.efi"
120120

121121
# global options.
122122
[options]
123-
# enable autoconfiguration by detecting bls enabled
124-
# filesystems and generating boot entries for them.
123+
# enable autoconfiguration by detecting installed kernels
124+
# generating boot entries for them.
125125
autoconfigure = true
126126
```
127127

@@ -130,14 +130,16 @@ If you do not have any drivers, exclude the drivers section entirely.
130130

131131
## Step 7: Configure Sprout Boot Entry
132132

133-
In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
133+
In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
134+
and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
135+
`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
134136

135137
```bash
136138
# For x86_64, run this command to add Sprout as the default boot entry.
137-
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
139+
$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
138140

139141
# For aarch64, run this command to add Sprout as the default boot entry.
140-
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
142+
$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
141143
```
142144

143145
Reboot your machine and it should boot into Sprout.

‎docs/setup/signed/fedora.md‎

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

‎docs/setup/signed/opensuse.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,11 +128,13 @@ If you do not have any drivers, exclude the drivers section entirely.
128128

129129
## Step 7: Configure Sprout Boot Entry
130130

131-
In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
131+
In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
132+
and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
133+
`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
132134

133135
```bash
134136
# Run this command to add Sprout as the default boot entry.
135-
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shim.efi'
137+
$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shim.efi'
136138
```
137139

138140
Reboot your machine and it should boot into Sprout.

‎docs/setup/signed/ubuntu.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,8 @@ path = "\\EFI\\sprout\\ext4.efi"
119119

120120
# global options.
121121
[options]
122-
# enable autoconfiguration by detecting bls enabled
123-
# filesystems and generating boot entries for them.
122+
# enable autoconfiguration by detecting installed kernels
123+
# generating boot entries for them.
124124
autoconfigure = true
125125
```
126126

@@ -129,14 +129,18 @@ If you do not have any drivers, exclude the drivers section entirely.
129129

130130
## Step 7: Configure Sprout Boot Entry
131131

132-
In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
132+
## Step 7: Configure Sprout Boot Entry
133+
134+
In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
135+
and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
136+
`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
133137

134138
```bash
135139
# For x86_64, run this command to add Sprout as the default boot entry.
136-
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
140+
$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
137141

138142
# For aarch64, run this command to add Sprout as the default boot entry.
139-
$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
143+
$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
140144
```
141145

142146
Reboot your machine and it should boot into Sprout.

0 commit comments

Comments
 (0)