arch-zbm/README.md

# arch-zbm

Helper script to install Arch Linux with ZFSBootMenu from within a running Arch Linux live CD ISO image

# Prep

We expect minimal prep on your end. Please make sure that before execution the following conditions are met.

- Arch Linux live CD ISO image sees exactly one partition with partition type code `BF00` ("Solaris root")
- Arch Linux live CD ISO image sees exactly one partition with partition type code `EF00` ("EFI system partition")
- No ZFS zpool exists

The script will create a single ZFS zpool `zpool` on the `BF00` partition with dataset child `zpool/root` which itself has one child `zpool/root/archlinux`, that's where Arch Linux gets installed. Parallel to `zpool/root` it'll create `zpool/data` with a `zpool/data/home` child dataset that gets mounted at `/home`.

The script will use the `EF00` partition to install a ZFSBootMenu EFI executable if `efibootmgr` says that no such `ZFSBootMenu` entry exists. If ZFSBootMenu gets added to the EFI partition it'll become primary boot option.

# How to run this?

- Boot an Arch Linux live CD ISO image
- Run:
    ```
    export SCRIPT_URL='https://quico.space/quico-os-setup/arch-zbm/raw/branch/main/setup.sh'
    curl -s "${SCRIPT_URL}" | bash
    ```
    During execution the script will call itself when it changes into its `chroot`, that's why we `export SCRIPT_URL`. Feel free to update `"${SCRIPT_URL}"` with whatever branch or revision you want to use from [quico.space/quico-os-setup/arch-zbm](https://quico.space/quico-os-setup/arch-zbm). Typically `.../branch/main/setup.sh` as shown above is what you want.

# Steps

The scripts takes the following installation steps.

1. Install ZFS tools and kernel module with [github.com/eoli3n/archiso-zfs](https://github.com/eoli3n/archiso-zfs)
1. Create one encrypted ZFS zpool on top of `BF00` partition, password `password`
1. Create dataset for Arch Linux and `/home`
1. Install Arch Linux into pool
1. Add ZFSBootMenu to `EF00` partition if it doesn't exist already
1. Exit into Arch Linux live CD ISO image shell for you to `reboot` and frolick

# Flavor choices

We make the following opinionated flavor choices. Feel free to change them to your liking.

- Arch Linux locale is set to `en_US.UTF-8`
- Keymap is `de-latin1`
    - Consult `/etc/vconsole.conf`
    - Change `zfs set org.zfsbootmenu:commandline=...`
- No X.Org Server, Wayland compositors or other GUI elements get installed
- Timezone is `Etc/UTC`
    - Check `timedatectl set-timezone <tzdata-zone>`

# Post-run manual steps

After installation you're going to want to at least touch these points in your new Arch Linux install:

- Package manager hook: `pacman` does not have a hook to do ZFS snapshots
    - See [this GitHub gist](https://gist.github.com/Soulsuke/6a7d1f09f7fef968a2f32e0ff32a5c4c#file-arch_on_zfs-txt-L238) and [zfs-snapshotter.bash](https://github.com/Soulsuke/arch-zfs-tools/blob/master/zfs-snapshotter.bash) for inspiration
- Hostname: Installation chose a pseudo-randomly generated 8-character string with `pwgen`
    - Check `hostnamectl set-hostname <hostname>`
- Unprivileged user accounts: The OS was installed with `root` and unprivileged `build` users
- Passwords
    - ZFS: The password for all datasets underneath `zpool` is `password`.
    - Local `root` account: The local `root` account's password is `password`.
- Arch User Repository (AUR) helper: We installed [paru](https://github.com/Morganamilo/paru) as our AUR helper, we installed from GitHub via `makepkg -si`.

# Development

## Conventional commits

This project uses [Conventional Commits](https://www.conventionalcommits.org/) for its commit messages.

### Commit types

Commit _types_ besides `fix` and `feat` are:

- `build`: Project structure, directory layout, build instructions for roll-out
- `refactor`: Keeping functionality while streamlining or otherwise improving function flow
- `test`: Working on test coverage
- `docs`: Documentation for project or components

### Commit scopes

The following _scopes_ are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:

- `iso`: Changing Arch Linux ISO CD
- `zbm`: Adjusting ZFSBootMenu's behavior
- `zfs`: A change to how ZFS interacts with the system, either a pool or a dataset
- `os`: Getting an perating system set up to correctly work in a ZFS boot environment
- `meta`: Affects the project's repo layout, readme content, file names etc.

# Credits

Most of what's here was shamelessly copied and slightly adapted for personal use from Jonathan Kirszling at GitHub.

Thanks to:

- Jonathan Kirszling:
    - [github.com/eoli3n/arch-config/tree/master/scripts/zfs/install](https://github.com/eoli3n/arch-config/tree/master/scripts/zfs/install)
    - [github.com/eoli3n/archiso-zfs](https://github.com/eoli3n/archiso-zfs)
- Maurizio Oliveri:
    - [github.com/Soulsuke/arch-zfs-tools](https://github.com/Soulsuke/arch-zfs-tools)
    - [gist.github.com/Soulsuke/6a7d1f09f7fef968a2f32e0ff32a5c4c](https://gist.github.com/Soulsuke/6a7d1f09f7fef968a2f32e0ff32a5c4c)
- Zach Dykstra,  Andrew J. Hesford and all other [ZFSBootMenu contributors](https://github.com/zbm-dev/zfsbootmenu/graphs/contributors):
    - Their [ZFSBootMenu testing helper scripts](https://github.com/zbm-dev/zfsbootmenu/tree/master/testing/helpers) ([chroot-arch.sh](https://github.com/zbm-dev/zfsbootmenu/blob/master/testing/helpers/chroot-arch.sh), [install-arch.sh](https://github.com/zbm-dev/zfsbootmenu/blob/master/testing/helpers/install-arch.sh))
- [github.com/kongkrit](https://github.com/kongkrit):
    - [gist.github.com/kongkrit/a0585e179e33c2adf92db4050ec5171d](https://gist.github.com/kongkrit/a0585e179e33c2adf92db4050ec5171d)