quico-os-setup/zfs-pacman-hook
1
0
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

refactor(docs): Adjust explanation of how we avoid naming collisions (#1)

Browse Source
This commit is contained in:
hygienic-books 2023-12-26 05:59:49 +01:00
parent 650a91f2cc
commit 525600dde4
1 changed files with 8 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@ -124,61 +124,19 @@ With these settings it is possible to cause ZFS snapshot name collisions (meanin
- They cover the same type of operation (_Install_, _Remove_ or _Upgrade_) - They cover the same type of operation (_Install_, _Remove_ or _Upgrade_)
- They cover the same list of packages - They cover the same list of packages
The script safeguards against naming collisions by adding a monotoniccally incrementing counter after the timestamp string.
For example by running `pacman -S tmux` three times within the same minute (once for an _Install_ operation and two more times for two identical _Upgrade_ operations) your system may generate the following example snapshots: For example by running `pacman -S tmux` three times within the same minute (once for an _Install_ operation and two more times for two identical _Upgrade_ operations) your system may generate the following example snapshots:
``` ```
zpool/root/archlinux@pacman_2023-03-07-0116_op:inst_sev:trv_pkgs:tmux zpool/root/archlinux@pacman_2023-03-07-0116_1_op:inst_sev:trv_pkgs:tmux
zpool/root/archlinux@pacman_2023-03-07-0116_op:upgr_sev:trv_pkgs:tmux zpool/root/archlinux@pacman_2023-03-07-0116_1_op:upgr_sev:trv_pkgs:tmux
zpool/root/archlinux@pacman_2023-03-07-0116_2_op:upgr_sev:trv_pkgs:tmux
~~~
``` ```
Notice that there is no third snapshot for the second identical _Upgrade_ operation as this script skipped snapshot creation. Notice that lines 2 and 3 would collide since their dataset names are virtually identical other than the counter suffix which was incremented by 1 to avoid a collision.
The rationale is that you're doing the exact same operation twice or more. There's most likely no reasonable expectaion that your operating system enters a different state on successive `pacman` operations so there's no need to deal with multiple snapshots capturing the same state. > This facilitates a hands-off approach to using this script on a daily driver system without risking missing snapshots or employing other more involved approaches to avoid naming collisions.
Your `pacman` command line output will show this like so:
```
:: Running pre-transaction hooks...
(1/1) Create ZFS snapshot(s)
[WARN] ZFS snapshot skipped (same operation exists at 2023-03-07-0116):
[WARN] zpool/root/archlinux@pacman_2023-03-07-0116_op:upgr_sev:trv_pkgs:tmux
[WARN] No ZFS snapshot left to do after accounting for identical operations at 2023-03-07-0116.
```
Note that this script will not blindly skip doing **_all_** snapshots in this situation. It will still happily create snapshots that don't cause naming collisions for example when affected snapshots were already deleted or when you're adding an additional dataset to the list of datasets you want to snapshot. In `pacman` command line output you'll then see warnings as needed and regular info-level messages for newly created snapshots where possible:
```
:: Running pre-transaction hooks...
(1/1) Create ZFS snapshot(s)
[WARN] ZFS snapshot skipped (same operation exists at 2023-03-07-0116):
[WARN] zpool/root/archlinux@pacman_2023-03-07-0116_op:upgr_sev:trv_pkgs:tmux
[WARN] zpool/root/archlinux/pacman-cache@pacman_2023-03-07-0116_op:upgr_sev:trv_pkgs:tmux
[INFO] ZFS snapshot atomically done:
[INFO] zpool/data/var/lib/docker@pacman_2023-03-07-0116_op:upgr_sev:trv_pkgs:tmux
```
This behavior is not configurable. During testing and development we considered adding a monotonically increasing counter to timestamps such as:
```
...2023-03-07-0116-1...
...2023-03-07-0116-2...
...2023-03-07-0116-3...
```
While this would effectively avoid naming collisions we decided against it. Weighing pros and cons the _skip_ approach seems ever so slightly simpler than the _counter_ approach.
## A word of warning
Note that skipping snapshot creation to avoid naming collisions can become overly dangerous if you strip away too many unique features from snapshot names. This may happen mostly in two ways:
1. Remove the package name list by setting `pkgs_list_max_length='0'`.
1. Remove distinguishing characters from timestamps via `snap_date_format='%F-%H%M'`
Without a package list two consecutive snapshots may look like so:
```
zpool/root/archlinux@pacman_2023-03-07-0116_op:inst_sev:trv
zpool/root/archlinux@pacman_2023-03-07-0116_op:upgr_sev:trv
```
If you then install any unrelated package within the same minute the `pacman` operation will be treated as identical to line 1 and this script will skip snapshot creation. Similarly if you lower timestamp fidelity to e.g. `%Y%m%d` (`20230307` instead of `2023-03-07-0116`) above example snapshots will look like so:
```
zpool/root/archlinux@pacman_20230307_op:inst_sev:trv
zpool/root/archlinux@pacman_20230307_op:upgr_sev:trv
```
All future _Install_ or _Upgrade_ operations within the same day will then also not be covered by snapshots. While this script will print warnings when it skips snapshot creation we suggest you change `pkgs_list_max_length` and `snap_date_format` options carefully. Defaults have proven to work well on example daily driver systems.
# Rollback # Rollback