57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
# zfs-pacman-hook
|
|
|
|
Arch Linux pacman hook for automatic ZFS snapshots
|
|
|
|
# Setup
|
|
|
|
Get started like so:
|
|
|
|
1. Install dependency `zfs-auto-snapshot`
|
|
1. Clone repo into arbitrary path `<repo>`
|
|
1. Make `pacman-zfs-snapshot.sh` executable
|
|
```
|
|
chmod +x <repo>/pacman-zfs-snapshot.sh
|
|
```
|
|
1. Symlink to files, for example
|
|
```
|
|
ln -s <repo>/pacman-zfs-snapshot.sh /usr/local/bin/pacman-zfs-snapshot
|
|
ln -s <repo>/pacman-zfs-snapshot.hook /usr/share/libalpm/hooks/pacman-zfs-snapshot.hook
|
|
ln -s <repo>/pacman-zfs-snapshot.conf /etc/pacman-zfs-snapshot.conf
|
|
```
|
|
Note that while you may choose arbitrary locations for symlinks the `pacman-zfs-snapshot.hook` file references `/usr/local/bin/pacman-zfs-snapshot`. Change that accordingly if you need to.
|
|
1. Adjust `pacman-zfs-snapshot.conf` to your liking
|
|
|
|
# What's it do?
|
|
|
|
In `pacman` on every `PreTransaction`, meaning right before any actual operation on a package begins, we trigger a ZFS snapshot. By default we identify the active system dataset by doing `findmnt / --noheadings --output source`. If exactly one source returns that is the exact name of a ZFS dataset in an imported zpool we create a snapshot on it. If no source returns we silently exit. If more than one source returns we raise an error and halt the `pacman` transaction.
|
|
|
|
We retain two different snapshot chains, one for `pacman` transactions that only affect what we are calling _trivial_ packages and a separate chain for _important_ packages. By default only the exact regular expression package name match `^linux$` is considered important. Whenever an important package is affected by a transaction a snapshot goes into the corresponding chain. In all other cases - when an important package is not affected - snapshots go into the trivial chain
|
|
|
|
We use `zfs-auto-snapshot` both for snapshot creation and for destroying old snapshots. The _trivial_ snapshot chain by default keeps 15 snapshots, the _important_ chain keeps 5. The thought process here is that you will likely not futz around with a kernel every day whereas you may very well install arbitrary packages multiple times a day. Snapshots should keep you safe for a couple of days hence the defaults of 5 and 15 snapshots, respectively.
|
|
|
|
You may optionally include more ZFS datasets in this snapshot mechanism. Have a look at `pacman-zfs-snapshot.conf`, its comments should be clear enough to get you going.
|
|
|
|
# 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:
|
|
|
|
- `auto`: Change how `zfs-auto-snapshot` is run
|
|
- `conf`: How we deal with script config
|
|
- `script`: Any other script work that doesn't specifically fall into the above scopes
|
|
- `meta`: Affects the project's repo layout, readme content, file names etc.
|