|
1 | 1 | # terraOS
|
2 | 2 | Boot Linux-based operating systems from a RMA shim.
|
3 | 3 |
|
4 |
| -## How do I use it? |
5 |
| -- Clone this repository. |
6 |
| -- Build the bootloader by running `sudo bash build.sh <input RMA shim> <output image path>`. |
7 |
| -- Flash it to a USB. |
8 |
| -- If you want to boot from squashfs, expand the 1st partition. |
9 |
| -- Copy all squashfses you want to boot from into the 1st partition. |
10 |
| -- For each rootfs you want to use with persistence, do these steps: |
11 |
| - - Create a new partition with type "ChromeOS rootfs" via fdisk or your favourite partitioning utility. |
12 |
| - - Format the partition. |
13 |
| - - Extract the tarball or bootstrap your rootfs as root into the root of the partition. If you are using `cp`, **make sure to use the `a` flag to preserve permissions and users**. To build the default rootfs, see [here](#how-do-i-build-the-terraos-rootfs). |
14 |
| - - Make sure the init program is at "/sbin/init" as that is the path that is executed. |
15 |
| - - TerraOS will autodetect all partitions on all GPT devices (including internal storage) with type "ChromeOS rootfs" and display them in a list that you can boot from. |
16 |
| - |
17 |
| -## FAQ |
18 |
| -### What works on the default rootfs? |
19 |
| -`make_rootfs.sh` copies firmware and modules from the RMA shim and ALSA kernel module configurations from the recovery image, so most if not all features should work out of the box. If features do not work, see [here](#crowdsourced-list-of-compatibility). |
20 |
| -- Systemd |
21 |
| -- Graphics |
22 |
| -- 3D Acceleration |
23 |
| -- Audio (this is board dependent) |
24 |
| -- WiFi (this is board dependent) |
25 |
| - |
26 |
| -### Can I use a different distro? |
27 |
| -Yes, you will need to either use a non-systemd distro or manually compile systemd with the [chromiumos patches](https://aur.archlinux.org/cgit/aur.git/tree/0002-Disable-mount_nofollow-for-ChromiumOS-kernels.patch?h=systemd-chromiumos). Then you can just follow the regular instructions and install your distro instead. |
28 |
| - |
29 |
| -### Can I use this without a USB in? |
30 |
| -Yes, you will need to create a "ChromeOS rootfs" partition on the internal storage and copy your rootfs there. In the future, there will be support for copying the filesystem to RAM. |
31 |
| - |
32 |
| -### Where is my WiFi, audio, etc?! |
33 |
| -Run `dmesg` and find the proper firmware for your board. Download it and manually add it to the rootfs. If you are using some exotic device it may not be in the RMA shim kernel. In that case you will have to compile the exact kernel version in the shim and then the module. |
34 |
| - |
35 |
| -## How do I build the TerraOS rootfs? |
36 |
| -**The password for the `terraos` user is `terraos`.** |
37 |
| -``` |
38 |
| -sudo bash create_rootfs.sh <rootfs path - needs to be empty> <shim> <board recovery image> <systemd-chromiumos.pkg.tar.zst> <systemd-chromiumos-libs.pkg.tar.zst> <systemd-chromiumos-sysvcompat.pkg.tar.zst> |
39 |
| -``` |
| 4 | + |
40 | 5 |
|
41 |
| -Then you can add extra firmware such as the ones from the crowdsourced list of firmware needed for WiFi below. |
| 6 | +## How does it work? |
| 7 | +terraOS utilizes a bug in chromebook RMA shims, which are bootable recovery images that are used for running diagnostic utilities, to chainload regular Linux distros by replacing the rootfs. Replacing the rootfs entirely doesn't work however, since the RMA shim boots in an environment made specifically for those diagnostic utilities. terraOS is made to get around that. |
42 | 8 |
|
43 |
| -To build systemd-chromiumos: |
44 |
| -``` |
45 |
| -git clone https://aur.archlinux.org/systemd-chromiumos |
46 |
| -cd systemd-chromiumos |
47 |
| -makepkg -Cs --skipinteg --nocheck |
48 |
| -``` |
| 9 | +## How do I add my own distros? |
| 10 | +You'll need to create a partition with the type `chromeOS rootfs` (`3cb8e202-3b7e-47dd-8a3c-7ff2a13cfcec`) and bootstrap your distro in the root of an ext4 filesystem on that partition. Place any squashfs files in the root of the first partition. |
49 | 11 |
|
50 |
| -`sudo tar cajvf ../<filename> *` seems to create a sane tarball of the generated rootfses. |
51 |
| -`sudo mksquashfs * ../<filename> -comp gzip` creates a squashfs image of the generated rootfs. |
52 |
| - |
53 |
| -## How do I build ChromeOS for TerraOS? |
54 |
| -``` |
55 |
| -sudo bash create_cros_persistent.sh <reven_recovery> <cros_recovery> <rma_shim> <path_to_image> |
56 |
| -``` |
57 |
| -The `path_to_image` must be a path to a file. |
58 |
| - |
59 |
| - |
60 |
| -## How do I build terrastage1.tar.zst? |
61 |
| -- Use the buildroot config located in this repo. |
62 |
| - |
63 |
| -## Crowdsourced list of compatibility |
64 |
| -If you get all features working on your TerraOS install, check here to make sure someone hasn't already posted data for your board and make a PR modifying this README. |
65 |
| - |
66 |
| -### Octopus |
67 |
| -All features work out of the box. Update your TerraOS rootfs, since this was fixed in a newer version. |
| 12 | +## How do I use it? |
| 13 | +1. Clone this repo. |
| 14 | +2. Create a build directory. |
| 15 | +3. Run `bash ../scripts/build_stage1.sh <defconfig>` |
| 16 | + - Use `terraos` as the defconfig if building for x86_64 chromebooks. |
| 17 | + - Use `terraos_jacuzzi` as the defconfig if building for `jacuzzi` board chromebooks. Support for `jacuzzi` board chromebooks is experimental and may not work, however. |
| 18 | +4. Run `bash ../scripts/build_aur_packages.sh` |
| 19 | +5. Run `bash ../scripts/build_all.sh <shim.bin> <board_recovery.bin> <reven_recovery.bin>` replacing `<shim.bin>` with the path to a shim for your board, `<board_recovery.bin>` with the path to a recovery image for your board, and `<reven_recovery.bin>` with the path to a chromeOS flex recovery of the same version. |
| 20 | + |
| 21 | +This will place a built bootloader image, squashfs and tarballs of the arch rootfs, a bootloader image with the arch rootfs, a bootloader image with terraOS chromeOS, and a bootloader image with both the arch rootfs and terraOS chromeOS in the build directory. |
| 22 | + |
| 23 | +## How do I install to internal storage? |
| 24 | +1. Boot into terraOS and copy over the image you used to flash your terraOS drive. |
| 25 | +2. Use GParted or `sudo fdisk -l` to find your internal storage. Replace `/dev/mmcblkX` in the rest of the steps with the internal storage device. |
| 26 | +3. Run `sudo dd if=<image> of=/dev/mmcblkX status=progress bs=16M oflag=direct` to write the image to the internal storage. Replace `<image>` with the path to the image you copied. |
| 27 | + |
| 28 | +Alternatively you can manually create a `chromeOS rootfs` type partition via `parted` or `fdisk`, format as ext4, and copy over the rootfs. |
| 29 | + |
| 30 | +## What doesn't work? |
| 31 | +- Deep sleep (kernel issue) |
| 32 | +- Swap (disabled in kernel) |
| 33 | +- Audio on dedede (firmware bug) |
| 34 | + |
| 35 | +## Can I use a different distro? |
| 36 | +Yes, you will need to either use a non-systemd distro or manually compile systemd with the [chromiumos patches](https://aur.archlinux.org/cgit/aur.git/tree/0002-Disable-mount_nofollow-for-ChromiumOS-kernels.patch?h=systemd-chromiumos). |
0 commit comments