min
/
shimboot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improve documentation

This commit is contained in:
ading2210 2024-04-29 01:17:45 -07:00
parent 8c522cd615
commit 1bc54d785b
1 changed files with 23 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@ -2,15 +2,26 @@
Shimboot is a collection of scripts for patching a Chrome OS RMA shim to serve as a bootloader for a standard Linux distribution. It allows you to boot a full desktop Debian install on a Chromebook, without needing to unenroll it or modify the firmware. Shimboot is a collection of scripts for patching a Chrome OS RMA shim to serve as a bootloader for a standard Linux distribution. It allows you to boot a full desktop Debian install on a Chromebook, without needing to unenroll it or modify the firmware.
## Features:
- Run a full Debian installation on a Chromebook
- Does not modify the firmware
- Works on enterprise enrolled devices
- Can boot Chrome OS with no restrictions (useful for enrolled devices)
- Nearly full device compatibility
- Optional disk compression
- Multiple desktop environments supported
## About: ## About:
Chrome OS RMA shims are bootable disk images which are designed to run a variety of diagnostic utilities on Chromebooks, and they'll work even if the device is enterprise enrolled. Unfortunately for Google, there exists a [security flaw](https://sh1mmer.me/) where the root filesystem of the RMA shim is not verified. This lets us replace the rootfs with anything we want, including a full Linux distribution. Chrome OS RMA shims are bootable disk images which are designed to run a variety of diagnostic utilities on Chromebooks, and they'll work even if the device is enterprise enrolled. Unfortunately for Google, there exists a [security flaw](https://sh1mmer.me/) where the root filesystem of the RMA shim is not verified. This lets us replace the rootfs with anything we want, including a full Linux distribution.
Simply replacing the shim's rootfs doesn't work, as it boots in an environment friendly to the RMA shim, not regular Linux distros. To get around this, a separate bootloader is required to transition from the shim environment to the main rootfs. This bootloader then does `pivot_root` to enter the rootfs, where it then starts the init system. Simply replacing the shim's rootfs doesn't work, as it boots in an environment friendly to the RMA shim, not regular Linux distros. To get around this, a separate bootloader is required to transition from the shim environment to the main rootfs. This bootloader then runs `pivot_root` to enter the rootfs, where it then starts the init system.
Another problem is encountered at this stage: the Chrome OS kernel will complain about systemd's mounts, and the boot process will hang. A simple workaround is to [apply a patch](https://github.com/ading2210/chromeos-systemd) to systemd, and then it can be recompiled and hosted at a [repo somewhere](https://github.com/ading2210/shimboot-repo). Another problem is encountered at this stage: the Chrome OS kernel will complain about systemd's mounts, and the boot process will hang. A simple workaround is to [apply a patch](https://github.com/ading2210/chromeos-systemd) to systemd, and then it can be recompiled and hosted at a [repo somewhere](https://github.com/ading2210/shimboot-repo).
After copying all the firmware from the recovery image and shim to the rootfs, we're able to boot to a mostly working XFCE desktop. After copying all the firmware from the recovery image and shim to the rootfs, we're able to boot to a mostly working XFCE desktop.
The main advantages of this approach are that you don't need to touch the device's firmware in order to run Linux. Simply rebooting and unplugging the USB drive will return the device to normal, which can be useful if the device is enterprise enrolled. However, since we are stuck with the kernel from the RMA shim, some features such as audio and suspend may not work.
### Partition Layout: ### Partition Layout:
1. 1MB dummy stateful partition 1. 1MB dummy stateful partition
2. 32MB Chrome OS kernel 2. 32MB Chrome OS kernel
@ -20,7 +31,7 @@ After copying all the firmware from the recovery image and shim to the rootfs, w
Note that rootfs partitions have to be named `shimboot_rootfs:<partname>` for the bootloader to recognize them. Note that rootfs partitions have to be named `shimboot_rootfs:<partname>` for the bootloader to recognize them.
## Status: ## Status:
Driver support depends on the device you are using shimboot on. This list is for the [`dedede`](https://chrome100.dev/board/dedede/) board, which is the only device I was able to do extensive testing on. The `patch_rootfs.sh` script attempts to copy all the firmware from the shim and recovery image into the rootfs, so expect most things to work on other boards. Driver support depends on the device you are using shimboot on. The `patch_rootfs.sh` script attempts to copy all the firmware and drivers from the shim and recovery image into the rootfs, so expect most things to work on other boards. ARM Chromebooks are not supported at the moment.
### Device Compatibility Table: ### Device Compatibility Table:
| Feature \ Board Name | [`dedede`](https://chrome100.dev/board/dedede/) | [`octopus`](https://chrome100.dev/board/octopus/) | [`reks`](https://chrome100.dev/board/reks/) | [`nissa`](https://chrome100.dev/board/nissa/) | | Feature \ Board Name | [`dedede`](https://chrome100.dev/board/dedede/) | [`octopus`](https://chrome100.dev/board/octopus/) | [`reks`](https://chrome100.dev/board/reks/) | [`nissa`](https://chrome100.dev/board/nissa/) |
@ -41,12 +52,14 @@ On all devices, the following features will not work:
- Swap (disabled by the kernel) - Swap (disabled by the kernel)
### TODO: ### TODO:
- Finish Python TUI rewrite - Finish Python TUI rewrite (see the `python` branch if you want to help with this)
- Transparent disk compression - Transparent disk compression
- Full disk encryption - Full disk encryption
- eliminate binwalk dependency - Support for more distros (Ubuntu and Arch maybe)
- get audio to work - Support for ARM based Chromebooks (see [issue #8](https://github.com/ading2210/shimboot/issues/8))
- get kexec working - Eliminate binwalk dependency
- Get audio to work on dedede
- Get kexec working
PRs and contributions are welcome to help implement these features. PRs and contributions are welcome to help implement these features.
@ -72,6 +85,8 @@ Alternatively, you can run each of the steps manually:
6. Run `sudo ./patch_rootfs.sh path_to_shim path_to_reco data/rootfs` to patch the base rootfs and add any needed drivers. 6. Run `sudo ./patch_rootfs.sh path_to_shim path_to_reco data/rootfs` to patch the base rootfs and add any needed drivers.
7. Run `sudo ./build.sh image.bin path_to_shim data/rootfs` to generate a disk image at `image.bin`. 7. Run `sudo ./build.sh image.bin path_to_shim data/rootfs` to generate a disk image at `image.bin`.
[Prebuilt images](https://github.com/ading2210/shimboot/releases) are available if you don't have a suitable device to run the build on.
### Booting the Image: ### Booting the Image:
1. Obtain a shimboot image by downloading a [prebuilt one](https://github.com/ading2210/shimboot/releases) or building it yourself. 1. Obtain a shimboot image by downloading a [prebuilt one](https://github.com/ading2210/shimboot/releases) or building it yourself.
2. Flash the shimboot image to a USB drive or SD card. Use the [Chromebook Recovery Utility](https://chrome.google.com/webstore/detail/chromebook-recovery-utili/pocpnlppkickgojjlmhdmidojbmbodfm) or [dd](https://linux.die.net/man/1/dd) if you're on Linux. 2. Flash the shimboot image to a USB drive or SD card. Use the [Chromebook Recovery Utility](https://chrome.google.com/webstore/detail/chromebook-recovery-utili/pocpnlppkickgojjlmhdmidojbmbodfm) or [dd](https://linux.die.net/man/1/dd) if you're on Linux.
@ -84,9 +99,9 @@ Alternatively, you can run each of the steps manually:
## FAQ: ## FAQ:
#### I want to use a different Linux distribution. How can I do that? #### I want to use a different Linux distribution. How can I do that?
Using any Linux distro is possible, provided that you apply the [proper patches](https://github.com/ading2210/chromeos-systemd) to systemd and recompile it. Most distros have some sort of bootstrapping tool that allows you to install it to a directory on your host PC. Then, you can just pass that rootfs dir into `build.sh`. Using any Linux distro is possible, provided that you apply the [proper patches](https://github.com/ading2210/chromeos-systemd) to systemd and recompile it. Most distros have some sort of bootstrapping tool that allows you to install it to a directory on your host PC. Then, you can just pass that rootfs directory into `patch_rootfs.sh` and `build.sh`.
Debian Sid (the unstable rolling release version of Debian) is also supported if you just want newer packages, and you can install it by passing an argument to `build_rootfs.sh`: Debian Sid (the rolling release version of Debian) is also supported if you just want newer packages, and you can install it by passing an argument to `build_rootfs.sh`:
```bash ```bash
sudo ./build_rootfs.sh data/rootfs unstable sudo ./build_rootfs.sh data/rootfs unstable
``` ```