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

improve documentation

This commit is contained in:
ading2210 2023-10-27 22:37:45 -07:00
parent 62ae740deb
commit 841f7b88ff
2 changed files with 39 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@ -20,6 +20,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.
### What Works: ### What Works:
- Systemd - Systemd
@ -49,7 +50,7 @@ Note that rootfs partitions have to be named `shimboot_rootfs:<partname>` for th
- ~~prompt user for hostname and account when creating the rootfs~~ - ~~prompt user for hostname and account when creating the rootfs~~
- ~~auto load iwlmvm~~ - ~~auto load iwlmvm~~
- get wifi fully working - get wifi fully working
- host prebuilt images - ~~host prebuilt images~~
- ~~write detailed documentation~~ - ~~write detailed documentation~~
### Long Term Goals: ### Long Term Goals:
@ -65,7 +66,7 @@ Note that rootfs partitions have to be named `shimboot_rootfs:<partname>` for th
- At least 20GB of free disk space - At least 20GB of free disk space
- An x86-based Chromebook - An x86-based Chromebook
### Instructions: ### Build Instructions:
1. Grab a Chrome OS RMA Shim from somewhere. Most of them have already been leaked and aren't too difficult to find. 1. Grab a Chrome OS RMA Shim from somewhere. Most of them have already been leaked and aren't too difficult to find.
2. Download a Chrome OS [recovery image](https://chromiumdash.appspot.com/serving-builds?deviceCategory=ChromeOS) for your board. 2. Download a Chrome OS [recovery image](https://chromiumdash.appspot.com/serving-builds?deviceCategory=ChromeOS) for your board.
3. Clone this repository and cd into it. 3. Clone this repository and cd into it.
@ -73,13 +74,30 @@ Note that rootfs partitions have to be named `shimboot_rootfs:<partname>` for th
5. Run `sudo ./build_rootfs.sh data/rootfs bookworm` to build the base rootfs. 5. Run `sudo ./build_rootfs.sh data/rootfs bookworm` to build the base rootfs.
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`.
8. Flash the generated image to a USB drive or SD card.
9. Enable developer mode on your Chromebook. Even if it's enrolled and dev mode is blocked, it'll still work for running shimboot.
10. Plug the USB into your Chromebook and enter recovery mode. It should detect the USB and run the shimboot bootloader.
Note that these instructions are currently incomplete. ### Booting the Image:
1. Obtain a shimboot image by downloading a [prebuilt one](https://dl.ading.dev/shimboot/) 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.
3. Enable developer mode on your Chromebook. If the Chromebook is enrolled, follow the instructions on the [sh1mmer website](https://sh1mmer.me) (see the "Executing on Chromebook" section).
4. Plug the USB into your Chromebook and enter recovery mode. It should detect the USB and run the shimboot bootloader.
5. Boot into Debian and log in with the username and password that you configured earlier. The default username/password for the prebuilt images is `user/user`.
6. Expand the rootfs partition so that it fills up the entire disk by running `sudo growpart /dev/sdX 4` (replacing `sdX` with the block device corresponding to your disk) to expand the partition, then running `sudo resize2fs /dev/sdX` to expand the filesystem.
## License: ## FAQ:
#### 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`.
#### How can I install a desktop environment other than XFCE?
Simply edit `rootfs/opt/setup_rootfs.sh`, and change the line after the `#install desktop` comment. By default, this is set to install XFCE using the `task-xfce-desktop` package, but you can change this to install whatever you want.
#### Will this prevent me from using Chrome OS normally?
Shimboot does not touch the internal storage at all, so you will be able to use Chrome OS as if nothing happened. However, if you are on an enterprise enrolled device, booting Chrome OS again will force a powerwash due to the attempted switch into developer mode.
## Copyright:
Shimboot is licensed under the [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.txt). Unless otherwise indicated, all code has been written by me, [ading2210](https://github.com/ading2210).
### Copyright Notice:
``` ```
ading2210/shimboot: Boot desktop Linux from a Chrome OS RMA shim. ading2210/shimboot: Boot desktop Linux from a Chrome OS RMA shim.
Copyright (C) 2023 ading2210 Copyright (C) 2023 ading2210

21
website/index.html
View File

@ -53,6 +53,8 @@
<a href="#usage" style="text-decoration: none;">5) Usage</a> <a href="#usage" style="text-decoration: none;">5) Usage</a>
<a href="#copyright" style="text-decoration: none;">6) Copyright</a> <a href="#copyright" style="text-decoration: none;">6) Copyright</a>
For more detailed information, please see the project's <a href="https://github.com/ading2210/shimboot">README</a>.
<b id="info">Info:</b> <b id="info">Info:</b>
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.
@ -74,18 +76,23 @@ For these images, the root password is "root". The name of the default user is "
1. Grab a Chrome OS RMA Shim from somewhere. Most of them have already been leaked and aren't too difficult to find. 1. Grab a Chrome OS RMA Shim from somewhere. Most of them have already been leaked and aren't too difficult to find.
2. Download a Chrome OS <a href="https://chromiumdash.appspot.com/serving-builds?deviceCategory=ChromeOS">recovery image</a> for your board. 2. Download a Chrome OS <a href="https://chromiumdash.appspot.com/serving-builds?deviceCategory=ChromeOS">recovery image</a> for your board.
3. Clone this repository and cd into it. 3. Clone this repository and cd into it.
4. Run `sudo ./build_rootfs.sh data/rootfs bookworm` to build the base rootfs. 4. Run `mkdir -p data/rootfs` to create a directory to hold the rootfs.
5. Run `sudo ./patch_rootfs.sh path_to_shim path_to_reco data/rootfs` to patch the base rootfs and add any needed drivers. 5. Run `sudo ./build_rootfs.sh data/rootfs bookworm` to build the base rootfs.
6. Run `sudo ./build.sh image.bin path_to_shim data/rootfs` to generate a disk image at `image.bin`. 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`.
<b id="usage">Usage:</b> <b id="usage">Usage:</b>
1. Obtain a shimboot image by downloading a prebuilt one or building it yourself. 1. Obtain a shimboot image by downloading a <a href="https://dl.ading.dev/shimboot/">prebuilt one</a> or building it yourself.
2. Flash the shimboot image to a USB drive or SD card. 2. Flash the shimboot image to a USB drive or SD card. Use the <a href="https://chrome.google.com/webstore/detail/chromebook-recovery-utili/pocpnlppkickgojjlmhdmidojbmbodfm">Chromebook Recovery Utility</a> or <a href="https://linux.die.net/man/1/dd">dd</a> if you're on Linux.
3. Enable developer mode on your Chromebook. Even if it's enrolled and dev mode is blocked, it'll still work. 3. Enable developer mode on your Chromebook. If the Chromebook is enrolled, follow the instructions on the <a href="https://sh1mmer.me">sh1mmer website</a> (see the "Executing on Chromebook" section).
4. Plug the USB into your Chromebook and enter recovery mode. It should detect the USB and run the shimboot bootloader. 4. Plug the USB into your Chromebook and enter recovery mode. It should detect the USB and run the shimboot bootloader.
5. Boot into Debian and log in with the username and password that you configured earlier. The default username/password for the prebuilt images is `user/user`.
6. Expand the rootfs partition so that it fills up the entire disk by running `sudo growpart /dev/sdX 4` (replacing `sdX` with the block device corresponding to your disk) to expand the partition, then running `sudo resize2fs /dev/sdX` to expand the filesystem.
<b id="copyright">Copyright:</b> <b id="copyright">Copyright:</b>
Shimboot is licensed under the <a href="https://www.gnu.org/licenses/gpl-3.0.txt">GNU GPL v3</a>. Unless otherwise indicated, all code has been written by me, <a href="https://ading.dev">@ading2210</a>. Shimboot is licensed under the <a href="https://www.gnu.org/licenses/gpl-3.0.txt">GNU GPL v3</a>. Unless otherwise indicated, all code has been written by me, <a href="https://ading.dev">ading2210</a>.
The source code for this project is available here: <a href="https://github.com/ading2210/shimboot">https://github.com/ading2210/shimboot</a>
Credit for fixing the original bug in systemd goes to <a href="https://github.com/r58Playz">@r58playz</a>. Credit for fixing the original bug in systemd goes to <a href="https://github.com/r58Playz">@r58playz</a>.