snap-pac-uki/README.md

# snap-pac-uki

Need help? Talk to me at [#snap-pac-uki:tfld.dev][matrix-room].

## What is this?

This is a collection of scripts, pacman hooks and and systemd units for creating
and managing unified kernel images (UKIs) based on snapper. It originally
expected to be executed as a pacman hook after `snap-pac`, but this is no longer
required (though the name remains).

## Installation

### Prerequisites

This tool expects that you already set up snapper. It also expects that each
snapshots linux and initramfs files (`/boot/vmlinuz-linux` and
`/boot/initramfs-linux.img`) as well as a kernel command line file
(`/etc/snap-pac-uki/kernel-cmd`) are available within each snapshot.

The fallback initramfs (`/boot/initramfs-linux-fallback.img`) and fallback
command line file (`/etc/snap-pac-uki/kernel-cmd-fallback`) are only required
on the current system.

Also the current command line file (`/etc/snap-pac-uki/kernel-cmd-current`)
needs is only required on the current system.

EFI boot options are only created for each snapshot. If you want the UKIs
created for the current system, you'll need to add boot entries yourself:

```bash
# template
efibootmgr -c \
    -d <EFI DEVICE> \
    -p <EFI PARTITION NUMBER> \
    -l <EFI PATH> \
    -L <LABEL>

# example
efibootmgr -c \
    -d /dev/nvme0n1 \
    -p 1 \
    -l "\EFI\Linux\arch-linux.efi" \
    -L "Arch Linux"

# example for fallback
efibootmgr -c \
    -d /dev/nvme0n1 \
    -p 1 \
    -l "\EFI\Linux\arch-linux-fallback.efi" \
    -L "Arch Linux (Fallback)"
```

### Using the install script

1. You can install the dependencies of this program with the following command:

   ```bash
   pacman -S fish efibootmgr jq ripgrep sbsigntools sed snapper
   ```

2. Download the latest release from [here][releases] and unpack it.

3. Then run the install script (you need to be in the same directory):

   ```bash
   ./install.fish
   ```

## Usage

### Creating snapshot UKIs

This creates a new UKI for all snapshots where none is found:

```bash
snap-pac-uki snapshots
```

### Create current UKIs

This creates a new UKI for the current system (including a fallback variant):

```bash
snap-pac-uki current
```

### Clean up UKIs

This removes all UKIs without corresponding snapshot (solely based on number):

```bash
snap-pac-uki clean
```

### Enable periodic cleanups using systemd timer

```
systemctl enable --now snap-pac-uki-cleanup.timer
```

## Uninstall

Simply run the following command in this directory:

```bash
./uninstall.fish
```

[matrix-room]: https://matrix.to/#/#snap-pac-uki:tfld.dev
[releases]: https://git.tfld.dev/tfld/snap-pac-uki/releases