mirror of
https://github.com/edera-dev/sprout.git
synced 2025-12-19 13:50:16 +00:00
chore(docs): reorganize setup guides
This commit is contained in:
113
docs/setup/unsigned/alpine-edge.md
Normal file
113
docs/setup/unsigned/alpine-edge.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Setup Sprout for Alpine Edge without Secure Boot
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Alpine Edge
|
||||
- EFI System Partition mounted on `/boot/efi` (the default)
|
||||
- ext4 or FAT32/exFAT formatted `/boot` partition
|
||||
|
||||
## Step 1: Base Installation
|
||||
|
||||
Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
|
||||
For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
|
||||
Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/boot/sprout.efi` on your EFI System Partition.
|
||||
|
||||
Additionally, you will want to install the `efifs` package, which provides the filesystem support for Sprout.
|
||||
|
||||
```bash
|
||||
# Install the efifs package which provides filesystem support for Sprout.
|
||||
$ apk install efifs
|
||||
```
|
||||
|
||||
## Step 2: Configure Sprout
|
||||
|
||||
Since Alpine uses standard image paths based on the `linux` package installed, it's quite easy to configure Sprout
|
||||
to boot Alpine.
|
||||
|
||||
Write the following file to `/boot/efi/sprout.toml`:
|
||||
|
||||
```toml
|
||||
# sprout configuration: version 1
|
||||
version = 1
|
||||
|
||||
# load an EFI driver for ext2/ext3/ext4.
|
||||
[drivers.ext2]
|
||||
path = "\\EFI\\efifs\\ext2.efi"
|
||||
|
||||
# extract the full path of the first filesystem
|
||||
# that contains \boot\vmlinuz-stable as a file
|
||||
# into the value called "root"
|
||||
[extractors.root.filesystem-device-match]
|
||||
has-item = "\\boot\\vmlinuz-stable"
|
||||
|
||||
# add a boot entry for booting linux
|
||||
# which will run the boot-linux action.
|
||||
[entries.boot-linux-stable]
|
||||
title = "Boot Linux Stable"
|
||||
actions = ["boot-linux-stable"]
|
||||
|
||||
# use the chainload action to boot linux-stable via the efi stub.
|
||||
# the options below are passed to the efi stub as the
|
||||
# kernel command line. the initrd is loaded using the efi stub
|
||||
# initrd loader mechanism.
|
||||
[actions.boot-linux-stable]
|
||||
chainload.path = "$root\\boot\\vmlinuz-stable"
|
||||
chainload.options = ["root=/dev/sda1", "my-kernel-option"]
|
||||
chainload.linux-initrd = "$root\\boot\\initramfs-stable"
|
||||
```
|
||||
|
||||
You can replace `vmlinuz-stable` and `initramfs-stable` with the actual
|
||||
files for the `linux` package you have installed. For example, for `linux-lts` it is `vmlinuz-lts` and `initramfs-lts`.
|
||||
|
||||
## Step 3, Option 1: Configure GRUB to load Sprout (recommended)
|
||||
|
||||
You can configure GRUB to add a boot entry for Sprout, so you can continue to use GRUB without interruption.
|
||||
|
||||
GRUB needs to be configured with the chainloader module to load Sprout.
|
||||
|
||||
You will need to find the UUID of your EFI System Partition. You can do this by running the following command:
|
||||
```bash
|
||||
$ grep "/boot/efi" /etc/fstab | awk '{print $1}' | awk -F '=' '{print $2}'
|
||||
SAMPLE-VALUE
|
||||
```
|
||||
|
||||
The GRUB configuration for Sprout is as follows, replace `SAMPLE-VALUE` with the UUID of your EFI System Partition:
|
||||
|
||||
```grub
|
||||
menuentry 'Sprout' $menuentry_id_option 'sprout' {
|
||||
insmod part_gpt
|
||||
insmod fat
|
||||
insmod chain
|
||||
search --no-floppy --fs-uuid --set=root SAMPLE-VALUE
|
||||
chainloader /EFI/boot/sprout.efi
|
||||
}
|
||||
```
|
||||
|
||||
You can append this to `/etc/grub.d/40_custom` and run the following command to update your configuration:
|
||||
```bash
|
||||
$ update-grub
|
||||
```
|
||||
|
||||
To update your GRUB configuration.
|
||||
|
||||
You may now reboot your system and select Sprout from the GRUB menu.
|
||||
|
||||
## Step 3, Option 2: Configure your EFI firmware for Sprout
|
||||
|
||||
You can configure your EFI boot menu to show Sprout as an option.
|
||||
|
||||
You will need to install the `efibootmgr` package:
|
||||
|
||||
```
|
||||
$ apk add efibootmgr
|
||||
```
|
||||
|
||||
Once `efibootmgr` is installed, find the partition device of your EFI System Partition and run the following:
|
||||
|
||||
```bash
|
||||
$ efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\boot\sprout.efi'
|
||||
```
|
||||
|
||||
This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration.
|
||||
|
||||
Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.
|
||||
118
docs/setup/unsigned/fedora.md
Normal file
118
docs/setup/unsigned/fedora.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Setup Sprout for Fedora without Secure Boot
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Modern Fedora release: tested on Fedora Workstation 42 and 43
|
||||
- EFI System Partition mounted on `/boot/efi` (the default)
|
||||
- ext4 or FAT32/exFAT formatted `/boot` partition
|
||||
|
||||
## Step 1: Base Installation
|
||||
|
||||
Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
|
||||
For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
|
||||
Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/BOOT/sprout.efi` on your EFI System Partition.
|
||||
|
||||
Additionally, you will want to install the `edk2-ext4` package, which provides the ext4 filesystem support for Sprout.
|
||||
|
||||
```bash
|
||||
# Install the edk2-ext4 package which provides ext4 support for Sprout.
|
||||
$ sudo dnf install edk2-ext4
|
||||
# Create a directory for sprout drivers.
|
||||
$ sudo mkdir -p /boot/efi/sprout/drivers
|
||||
# For x86_64 systems, copy the ext4x64.efi driver to the sprout drivers directory.
|
||||
$ sudo cp /usr/share/edk2/drivers/ext4x64.efi /boot/efi/sprout/drivers/ext4.efi
|
||||
# For ARM64 systems, copy the ext4aa64.efi driver to the sprout drivers directory.
|
||||
$ sudo cp /usr/share/edk2/drivers/ext4aa64.efi /boot/efi/sprout/drivers/ext4.efi
|
||||
```
|
||||
|
||||
## Step 2: Configure Sprout
|
||||
|
||||
Since Fedora uses the BLS specification, you can use the `bls` generator to autoconfigure Sprout for Fedora.
|
||||
|
||||
Write the following file to `/boot/efi/sprout.toml`:
|
||||
|
||||
```toml
|
||||
# sprout configuration: version 1
|
||||
version = 1
|
||||
|
||||
# load an EFI driver for ext4.
|
||||
[drivers.ext4]
|
||||
path = "\\sprout\\drivers\\ext4.efi"
|
||||
|
||||
# global options.
|
||||
[options]
|
||||
# enable autoconfiguration by detecting bls enabled
|
||||
# filesystems and generating boot entries for them.
|
||||
autoconfigure = true
|
||||
```
|
||||
|
||||
## Step 3, Option 1: Configure GRUB to load Sprout (recommended)
|
||||
|
||||
You can configure GRUB to add a boot entry for Sprout, so you can continue to use GRUB without interruption.
|
||||
|
||||
GRUB needs to be configured with the chainloader module to load Sprout.
|
||||
|
||||
### x86_64
|
||||
|
||||
```bash
|
||||
# Install x86_64 GRUB modules.
|
||||
$ sudo dnf install grub2-efi-x64-modules
|
||||
# Copy x86_64 GRUB modules to /boot/grub2 for use by GRUB if it isn't installed already.
|
||||
$ [ ! -d /boot/grub2/x86_64-efi ] && sudo cp -r /usr/lib/grub/x86_64-efi /boot/grub2/x86_64-efi
|
||||
```
|
||||
|
||||
### ARM64
|
||||
|
||||
```bash
|
||||
# Install ARM64 GRUB modules.
|
||||
$ sudo dnf install grub2-efi-aa64-modules
|
||||
# Copy ARM64 GRUB modules to /boot/grub2 for use by GRUB if it isn't installed already.
|
||||
$ [ ! -d /boot/grub2/arm64-efi ] && sudo cp -r /usr/lib/grub/arm64-efi /boot/grub2/x86_64-efi
|
||||
```
|
||||
|
||||
You will need to find the UUID of your EFI System Partition. You can do this by running the following command:
|
||||
```bash
|
||||
$ grep "/boot/efi" /etc/fstab | awk '{print $1}' | awk -F '=' '{print $2}'
|
||||
SAMPLE-VALUE
|
||||
```
|
||||
|
||||
The GRUB configuration for Sprout is as follows, replace `SAMPLE-VALUE` with the UUID of your EFI System Partition:
|
||||
|
||||
```grub
|
||||
menuentry 'Sprout' $menuentry_id_option 'sprout' {
|
||||
insmod part_gpt
|
||||
insmod fat
|
||||
insmod chain
|
||||
search --no-floppy --fs-uuid --set=root SAMPLE-VALUE
|
||||
chainloader /EFI/BOOT/sprout.efi
|
||||
}
|
||||
```
|
||||
|
||||
You can append this to `/etc/grub.d/40_custom` and run the following command to update your configuration:
|
||||
```bash
|
||||
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
|
||||
```
|
||||
|
||||
To update your GRUB configuration.
|
||||
|
||||
Make sure to update your GRUB environment to show the menu:
|
||||
|
||||
```bash
|
||||
$ sudo grub2-editenv - set menu_auto_hide=0
|
||||
```
|
||||
|
||||
You may now reboot your system and select Sprout from the GRUB menu.
|
||||
|
||||
## Step 3, Option 2: Configure your EFI firmware for Sprout
|
||||
|
||||
You can configure your EFI boot menu to show Sprout as an option.
|
||||
|
||||
To do so, please find the partition device of your EFI System Partition and run the following:
|
||||
|
||||
```bash
|
||||
$ sudo efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\BOOT\sprout.efi'
|
||||
```
|
||||
|
||||
This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration.
|
||||
|
||||
Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.
|
||||
62
docs/setup/unsigned/generic-linux.md
Normal file
62
docs/setup/unsigned/generic-linux.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Setup Sprout for Linux without Secure Boot
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- EFI System Partition mounted on a known path
|
||||
- Linux kernel installed with an optional initramfs
|
||||
- Linux kernel must support the EFI stub (most distro kernels)
|
||||
|
||||
## Step 1: Base Installation
|
||||
|
||||
First, identify the path to your EFI System Partition. On most systems, this is `/boot/efi`.
|
||||
|
||||
Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
|
||||
For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
|
||||
Copy the downloaded `sprout.efi` file to `/EFI/BOOT/sprout.efi` on your EFI System Partition.
|
||||
|
||||
## Step 2: Copy kernel and optional initramfs
|
||||
|
||||
Copy the Linux kernel to `/vmlinuz-sprout` on your EFI System Partition.
|
||||
If needed, copy the initramfs to `/initramfs-sprout` on your EFI System Partition.
|
||||
|
||||
## Step 3: Configure Sprout
|
||||
|
||||
Write the following file to `/sprout.toml` on your EFI System Partition,
|
||||
paying attention to place the correct values:
|
||||
|
||||
```toml
|
||||
# sprout configuration: version 1
|
||||
version = 1
|
||||
|
||||
# add a boot entry for booting linux
|
||||
# which will run the boot-linux action.
|
||||
[entries.boot-linux]
|
||||
title = "Boot Linux"
|
||||
actions = ["boot-linux"]
|
||||
|
||||
# use the chainload action to boot linux via the efi stub.
|
||||
# the options below are passed to the efi stub as the
|
||||
# kernel command line. the initrd is loaded using the efi stub
|
||||
# initrd loader mechanism.
|
||||
[actions.boot-linux]
|
||||
chainload.path = "\\vmlinuz-sprout"
|
||||
chainload.options = ["root=/dev/sda1", "my-kernel-option"]
|
||||
chainload.linux-initrd = "\\initramfs-sprout"
|
||||
```
|
||||
|
||||
You can specify any kernel command line options you want on the chainload options line.
|
||||
They will be concatenated by a space and passed to the kernel.
|
||||
|
||||
## Step 4: Configure EFI firmware to boot Sprout
|
||||
|
||||
Since Sprout is still experimental, the following commands will add a boot entry to your EFI firmware for sprout but
|
||||
intentionally do not set it as the default boot entry.
|
||||
|
||||
To add the entry, please find the partition device of your EFI System Partition and run the following:
|
||||
|
||||
```bash
|
||||
$ sudo efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\BOOT\sprout.efi'
|
||||
```
|
||||
|
||||
This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration.
|
||||
Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.
|
||||
47
docs/setup/unsigned/windows.md
Normal file
47
docs/setup/unsigned/windows.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Setup Sprout for Windows without Secure Boot
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Secure Boot is disabled or configured to allow Sprout
|
||||
- UEFI Windows installation
|
||||
|
||||
## Step 1: Base Installation
|
||||
|
||||
First, mount the EFI System Partition on your Windows installation:
|
||||
|
||||
In an administrator command prompt, run:
|
||||
|
||||
```batch
|
||||
> mountvol X: /s
|
||||
```
|
||||
|
||||
This will mount the EFI System Partition to the drive letter `X:`.
|
||||
|
||||
Please note that Windows Explorer will not let you see the drive letter `X:` where the ESP is mounted.
|
||||
You will need to use the command prompt or PowerShell to access the ESP.
|
||||
Standard editors can, however, be used to edit files on the ESP.
|
||||
|
||||
Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
|
||||
For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
|
||||
Copy the downloaded `sprout.efi` file to `X:\EFI\BOOT\sprout.efi` on your EFI System Partition.
|
||||
|
||||
## Step 3: Configure Sprout
|
||||
|
||||
Write the following file to `X:\sprout.toml`:
|
||||
|
||||
```toml
|
||||
# sprout configuration: version 1
|
||||
version = 1
|
||||
|
||||
# global options.
|
||||
[options]
|
||||
# enable autoconfiguration to detect Windows.
|
||||
autoconfigure = true
|
||||
```
|
||||
|
||||
## Step 4: Configure EFI Firmware to boot Sprout
|
||||
|
||||
It is not trivial to add an EFI boot entry inside Windows.
|
||||
However, most firmware lets you load arbitrary EFI files from the firmware settings.
|
||||
|
||||
You can boot `\EFI\BOOT\sprout.efi` from firmware to boot Sprout.
|
||||
Reference in New Issue
Block a user