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

While not depending on it directly, this tool expects that you already set up
snapper. It expects, that each snapshot contains its kernel
(`/boot/vmlinuz-linux`) and initramfs (`/boot/intitramfs-linux.img`), as well as
a kernel command line file (`/etc/snap-pac-uki/kernel-cmd`).

For generating the current and fallback UKIs, the kernel and initramfs files of
the currently running system are used. For a kernel cmd, it uses
`/etc/snap-pac-uki/kernel-cmd-current` and `/etc/snap-pac-uki/kernel-cmd-fallback`.

If you want to boot a UKI directly, use the `efibootmgr` command to create an
entry.

```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 ripgrep sbsigntools sed
   ```

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