From 562ffbdc0f567dd6fb373c5e7c1f3de67c8e7019 Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 05:56:56 +0100 Subject: [PATCH 1/9] refactor(script): Put ZFS property in a variable (#1) --- pacman-zfs-snapshot.sh | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/pacman-zfs-snapshot.sh b/pacman-zfs-snapshot.sh index 438e939..116696a 100755 --- a/pacman-zfs-snapshot.sh +++ b/pacman-zfs-snapshot.sh @@ -31,7 +31,8 @@ snap_op_remove_suffix="${snap_op_remove_suffix:-rmvl}" snap_op_upgrade_suffix="${snap_op_upgrade_suffix:-upgr}" # Internal -declare pkg_separator max_zfs_snapshot_name_length color_reset color_lyellow color_red +declare zfs_prop pkg_separator max_zfs_snapshot_name_length color_reset color_lyellow color_red +zfs_prop='space.quico:auto-snapshot' pkg_separator=':' max_zfs_snapshot_name_length='255' color_reset='\e[0m' @@ -95,12 +96,12 @@ function set_severity () { function get_globally_snappable_datasets () { local datasets_list - # For all datasets show their 'space.quico:auto-snapshot' property; only - # print dataset name in column 1 and property value in column 2. In awk - # limit this list to datasets where tab-delimited column 2 has exact - # string '^true$' then further limit output by eliminating snapshots - # from list, i.e. dataset names that contain an '@' character. - datasets_list="$(zfs get -H -o 'name,value' 'space.quico:auto-snapshot' | \ + # For all datasets show their "${zfs_prop}" property; only print dataset + # name in column 1 and property value in column 2. In awk limit this + # list to datasets where tab-delimited column 2 has exact string + # '^true$' then further limit output by eliminating snapshots from list, + # i.e. dataset names that contain an '@' character. + datasets_list="$(zfs get -H -o 'name,value' "${zfs_prop}" | \ awk -F'\t' '{if($2 ~ /^true$/ && $1 !~ /@/) print $1}')" while IFS= read -u10 -r dataset; do globally_snappable_datasets+=("${dataset}") From c23567e2b17fb840db6c06019f9ecb5212da01a0 Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 05:57:22 +0100 Subject: [PATCH 2/9] refactor(script): Space out error messages correctly (#1) --- pacman-zfs-snapshot.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pacman-zfs-snapshot.sh b/pacman-zfs-snapshot.sh index 116696a..d047d8b 100755 --- a/pacman-zfs-snapshot.sh +++ b/pacman-zfs-snapshot.sh @@ -64,7 +64,7 @@ function pprint () { printf -- "${color_lyellow}"'[WARN]'"${color_reset}"' %s\n' "${msg}" ;; err) - printf -- "${color_red}"'[ERR]'"${color_reset}"' %s\n' "${msg}" + printf -- "${color_red}"'[ERR] '"${color_reset}"' %s\n' "${msg}" ;; info) printf -- '[INFO] %s\n' "${msg}" From ff963aa844c9d0f3a27a59ae908a324524c7d949 Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 05:58:07 +0100 Subject: [PATCH 3/9] refactor(script): Abort early and with clear msg when no datasets snapshottable (#1) --- pacman-zfs-snapshot.sh | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/pacman-zfs-snapshot.sh b/pacman-zfs-snapshot.sh index d047d8b..b7d643a 100755 --- a/pacman-zfs-snapshot.sh +++ b/pacman-zfs-snapshot.sh @@ -375,8 +375,18 @@ function main () { local local_snappable_datasets get_local_snappable_datasets trim_globally_snappable_datasets + if [[ "${#snappable_datasets[@]}" -eq '0' ]]; then + pprint 'info' 'ZFS snapshot skipped, no local (= currently mounted) dataset has' + pprint 'info' 'property '"'"''"${zfs_prop}"''"'"' set to '"'"'true'"'"'. At the same' + pprint 'info' 'time option '"'"'snap_only_local_datasets'"'"' equals '"'"'true'"'"' so' + pprint 'info' 'we must only snapshot local datasets. Nothing to do here while' + pprint 'info' 'none of them have '"'"''"${zfs_prop}"''"'"' set to '"'"'true'"'"'.' '0' + fi else snappable_datasets=("${globally_snappable_datasets}") + if [[ "${#snappable_datasets[@]}" -eq '0' ]]; then + pprint 'info' 'ZFS snapshot skipped, no dataset has property '"'"''"${zfs_prop}"''"'"' set to '"'"'true'"'"'.' '0' + fi fi local unabridged_pkg_list_oneline From 917a71ced483a56259f125603474193cd1bf8aed Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 05:58:34 +0100 Subject: [PATCH 4/9] feat(script): Avoid snap name collisions, always append counter to make them unique (#1) --- pacman-zfs-snapshot.sh | 190 ++++++++++++++++++++--------------------- 1 file changed, 95 insertions(+), 95 deletions(-) diff --git a/pacman-zfs-snapshot.sh b/pacman-zfs-snapshot.sh index b7d643a..3a9d6be 100755 --- a/pacman-zfs-snapshot.sh +++ b/pacman-zfs-snapshot.sh @@ -148,39 +148,6 @@ function write_pkg_list_oneline () { fi } -function find_max_dataset_name_length () { - local longest_op_suffix op_suffix_string - longest_op_suffix='0' - for op_suffix in "${snap_op_installation_suffix}" "${snap_op_remove_suffix}" "${snap_op_upgrade_suffix}"; do - if [[ "${#op_suffix}" -gt "${longest_op_suffix}" ]]; then - longest_op_suffix="${#op_suffix}" - fi - done - op_suffix_string="$(head -c "${longest_op_suffix}" '/dev/zero' | tr '\0' '_')" - - local longest_sev_suffix sev_suffix_string - longest_sev_suffix='0' - for sev_suffix in "${snaps_trivial_suffix}" "${snaps_important_suffix}"; do - if [[ "${#sev_suffix}" -gt "${longest_sev_suffix}" ]]; then - longest_sev_suffix="${#sev_suffix}" - fi - done - sev_suffix_string="$(head -c "${longest_sev_suffix}" '/dev/zero' | tr '\0' '_')" - - local dataset_name_no_pkgs - max_dataset_name_length='0' - for dataset in "${snappable_datasets[@]}"; do - dataset_name_no_pkgs="${dataset}"'@'"${snap_name_prefix}${snap_field_separator}${date_string}${snap_field_separator}"'op:'"${op_suffix_string}${snap_field_separator}"'sev:'"${sev_suffix_string}${snap_field_separator}"'pkgs:' - if [[ "${#dataset_name_no_pkgs}" -gt "${max_dataset_name_length}" ]]; then - max_dataset_name_length="${#dataset_name_no_pkgs}" - fi - done - - if [[ "${max_dataset_name_length}" -gt "${max_zfs_snapshot_name_length}" ]]; then - pprint 'warn' 'Snapshot name would exceed ZFS '"${max_zfs_snapshot_name_length}"' chars limit. Skipping snapshots ...' '0' - fi -} - function trim_single_remaining_package_name () { local pkg_name pkg_name="${shorter_pkg_list}" @@ -201,7 +168,7 @@ function trim_single_remaining_package_name () { function trim_pkg_list_oneline () { local available_pkg_list_length - available_pkg_list_length="$((${max_zfs_snapshot_name_length} - ${max_dataset_name_length}))" + available_pkg_list_length="${1}" if [[ "${available_pkg_list_length}" -lt "${pkgs_list_max_length}" ]]; then # If we have fewer characters available before hitting the # ZFS internal maximum snapshot name length than the user @@ -236,74 +203,109 @@ function trim_pkg_list_oneline () { trimmed_pkg_list_oneline="${shorter_pkg_list}" } -function omit_duplicate_snaps () { - local existing_snaps - local -a unneeded_snaps - existing_snaps="$(zfs list -t all -oname -H)" +function test_snap_names_for_validity () { + local snap_counter max_dataset_name_length trimmed_pkg_list_oneline dataset_name_no_pkgs dataset_name_with_pkgs + snap_counter="${1}" + max_dataset_name_length='0' + for dataset in "${snappable_datasets[@]}"; do + # Begin building snapshot name + dataset_name_no_pkgs="${dataset}"'@'"${snap_name_prefix}${snap_field_separator}${date_string}" - for planned_snap in "${planned_snaps[@]}"; do - if grep -Piq -- '^'"${planned_snap}"'$' <<<"${existing_snaps}"; then - unneeded_snaps+=("${planned_snap}") - else - needed_snaps+=("${planned_snap}") + # Append counter + dataset_name_no_pkgs="${dataset_name_no_pkgs}${snap_field_separator}${snap_counter}" + + # Append operation, severity and packages fields + dataset_name_no_pkgs="${dataset_name_no_pkgs}${snap_field_separator}"'op:'"${conf_op_suffix}${snap_field_separator}"'sev:'"${severity}" + + # Update the longest snapshot name seen so far. We add an automatic + # +6 to string length (or more exactly ${#snap_field_separator}+5) + # to account for the fact that by default the dataset will end in + # the separator string "${snap_field_separator}" plus 'pkgs:' for a + # total of 6 additional characters. If these additional characters + # cause us to reach or go over the ZFS dataset name length limit + # there's no point in attempting to add package names to snapshots. + # We calculate as if these additional characters existed and we add + # dataset names to our planned_snaps array as if they don't. + if [[ "$(( ${#dataset_name_no_pkgs}+${#snap_field_separator}+5 ))" -gt "${max_dataset_name_length}" ]]; then + max_dataset_name_length="$(( ${#dataset_name_no_pkgs}+${#snap_field_separator}+5 ))" fi + + planned_snaps+=("${dataset_name_no_pkgs}") done - if [[ "${#unneeded_snaps[@]}" -gt '0' ]]; then - if [[ "${do_dry_run}" == 'true' ]]; then - pprint 'warn' 'Dry-run, ZFS snapshot skipped (same operation exists at '"${date_string}"'):' - else - pprint 'warn' 'ZFS snapshot skipped (same operation exists at '"${date_string}"'):' + # Abort if this is longer than what ZFS allows + if [[ "${max_dataset_name_length}" -gt "${max_zfs_snapshot_name_length}" ]]; then + pprint 'err' 'Snapshot name would exceed ZFS '"${max_zfs_snapshot_name_length}"' chars limit. Aborting ...' '1' + fi + + if [[ "${max_dataset_name_length}" -eq "${max_zfs_snapshot_name_length}" ]]; then + for planned_snap in "${planned_snaps[@]}"; do + if grep -Piq -- '^'"${planned_snap}"'$' <<<"${existing_snaps}"; then + # This snapshot name already exists. Unset array and break. + # Try again with next higher counter suffix. + unset planned_snaps[@] + break + fi + done + # If planned_snaps array still has members we take the snapshot + # names already generated. If not we return without array in which + # case this function will run again with the snapshot counter + # incremented by one. Maximum length seen across all snapshot names + # is exactly the ZFS snapshot character limit. We won't be able to + # add packages to snapshot names but they will all fit perfectly. + # This is good enough. + return + else + # We have enough room to add package names. + local available_pkg_list_length + available_pkg_list_length="${pkgs_list_max_length}" + if [[ "${max_dataset_name_length}" -gt $(( max_zfs_snapshot_name_length - pkgs_list_max_length )) ]]; then + available_pkg_list_length="$(( max_zfs_snapshot_name_length - max_dataset_name_length ))" fi - for unneeded_snap in "${unneeded_snaps[@]}"; do - pprint 'warn' ' '"${unneeded_snap}" + trim_pkg_list_oneline "${available_pkg_list_length}" + for planned_snap_id in "${!planned_snaps[@]}"; do + planned_snaps["${planned_snap_id}"]="${planned_snaps[${planned_snap_id}]}${snap_field_separator}"'pkgs:'"${trimmed_pkg_list_oneline}" + if grep -Piq -- '^'"${planned_snaps[${planned_snap_id}]}"'$' <<<"${existing_snaps}"; then + # This snapshot name already exists. Unset array and break. + # Try again with next higher counter suffix. + unset planned_snaps[@] + break + fi done fi } -function do_snaps () { - local snap_name snap_return_code - local -a planned_snaps - for snappable_dataset_id in "${!snappable_datasets[@]}"; do - snap_name="${snappable_datasets[${snappable_dataset_id}]}"'@'"${snap_name_prefix}${snap_field_separator}${date_string}${snap_field_separator}"'op:'"${conf_op_suffix}${snap_field_separator}"'sev:'"${severity}" - # If we have at least one pkg name character to append we do - # so now but if we're not even allowed to append a single - # character we might as well skip the 'pkgs' field - # altogether. - if [[ "${pkgs_list_max_length}" -ge '1' ]]; then - snap_name="${snap_name}${snap_field_separator}"'pkgs:'"${trimmed_pkg_list_oneline}" - fi - planned_snaps["${snappable_dataset_id}"]="${snap_name}" +function generate_snap_names () { + local snap_counter existing_snaps + snap_counter='0' + existing_snaps="$(zfs list -t all -oname -H)" + until [[ "${#planned_snaps[@]}" -gt '0' ]]; do + snap_counter="$(( snap_counter+1 ))" + test_snap_names_for_validity "${snap_counter}" done - local -a needed_snaps - omit_duplicate_snaps - if [[ "${#needed_snaps[@]}" -gt '0' ]]; then - if [[ "${do_dry_run}" == 'true' ]]; then - pprint 'info' 'Dry-run, pretending to atomically do ZFS snapshot:' - for needed_snap in "${needed_snaps[@]}"; do - pprint 'info' ' '"${needed_snap}" +} + +function do_snaps () { + local snap_return_code + if [[ "${do_dry_run}" == 'true' ]]; then + pprint 'info' 'Dry-run, pretending to atomically do ZFS snapshot:' + for planned_snap in "${planned_snaps[@]}"; do + pprint 'info' ' '"${planned_snap}" + done + else + zfs snapshot "${planned_snaps[@]}" + snap_return_code="${?}" + if [[ "${snap_return_code}" -eq '0' ]]; then + successfully_snapped_datasets=("${snappable_datasets[@]}") + pprint 'info' 'ZFS snapshot atomically done:' + for planned_snap in "${planned_snaps[@]}"; do + pprint 'info' ' '"${planned_snap}" done else - zfs snapshot "${needed_snaps[@]}" - snap_return_code="${?}" - if [[ "${snap_return_code}" -eq '0' ]]; then - successfully_snapped_datasets=("${snappable_datasets[@]}") - pprint 'info' 'ZFS snapshot atomically done:' - for needed_snap in "${needed_snaps[@]}"; do - pprint 'info' ' '"${needed_snap}" - done - else - pprint 'warn' 'ZFS snapshot failed:' - for needed_snap in "${needed_snaps[@]}"; do - pprint 'warn' ' '"${needed_snap}" - done - fi - fi - else - if [[ "${do_dry_run}" == 'true' ]]; then - pprint 'warn' 'Dry-run, no ZFS snapshot left to do after accounting for identical operations at '"${date_string}"'.' - else - pprint 'warn' 'No ZFS snapshot left to do after accounting for identical operations at '"${date_string}"'.' + pprint 'warn' 'ZFS snapshot failed:' + for planned_snap in "${planned_snaps[@]}"; do + pprint 'warn' ' '"${planned_snap}" + done fi fi } @@ -392,12 +394,10 @@ function main () { local unabridged_pkg_list_oneline write_pkg_list_oneline - local date_string max_dataset_name_length + local date_string + local -a planned_snaps date_string="$($([[ "${snap_timezone}" ]] && printf -- 'export TZ='"${snap_timezone}"); date +"${snap_date_format}")" - find_max_dataset_name_length - - local trimmed_pkg_list_oneline - trim_pkg_list_oneline + generate_snap_names local -a successfully_snapped_datasets do_snaps From 650a91f2cc2317612bbbd25e38ac63d42eaf779b Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 05:59:12 +0100 Subject: [PATCH 5/9] refactor(docs): Fix incorrect explanation how we identify snapshottable datasets (#1) --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e354081..4095b73 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,14 @@ Hook files from both directories are collectively parsed and executed in lexicog For ZFS snapshots intended to save your bacon the `00-*` naming convention is particularly critical. In `/usr/share/libalpm/hooks` you can see for example that when a kernel upgrade happens `60-mkinitcpio-remove.hook` is executed (deleting your existing `vmlinuz-*` kernel image for example at `/boot/vmlinuz-linux`). After that if you're using the `zfs-dkms` package which itself requires `dkms` which in turn installs `71-dkms-remove.hook` this hook removes your ZFS kernel module files. Both the `60-*` and optionally the `71-*` hook (for `zfs-dkms` users) run early due to their naming. If we don't create a snapshot before these hooks run we end up creating a snapshot without kernel image and without ZFS kernel module files. Our `00-*` hook files are executed early enough ensuring that a snapshot can safely return you to a working system. -By default we identify the active system dataset by doing `findmnt / --noheadings --output source` which for example returns: +We snapshot datasets that have the `space.quico:auto-snapshot` property set to `true`. By default we further limit datasets to only those that are currently mounted in your active operating system. We identify these by asking `findmnt` for a list of mounted file systems of `fstype=="zfs"` which for example returns: ``` +# findmnt --json --list --output 'fstype,source,target' | \ + jq --raw-output '.[][] | select(.fstype=="zfs") | .source' + zpool/root/archlinux ``` -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. +If no dataset (or no _local_ dataset) has the property set correctly no snapshots are done. The script will print an info-level message about that on `pacman` transactions. 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(-zen)?(-headers)?|systemd|zfs-(linux(-zen)?|dkms|utils))$` is considered important so in plain English any one of: From 525600dde472c3fb24a21bb5434fec61590d73d0 Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 05:59:49 +0100 Subject: [PATCH 6/9] refactor(docs): Adjust explanation of how we avoid naming collisions (#1) --- README.md | 58 ++++++++----------------------------------------------- 1 file changed, 8 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 4095b73..60826ff 100644 --- a/README.md +++ b/README.md @@ -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 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: ``` -zpool/root/archlinux@pacman_2023-03-07-0116_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:inst_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. - -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. +> 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. # Rollback From 3516f56580dc19abafd028f7f0ebf395d007e934 Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 06:09:43 +0100 Subject: [PATCH 7/9] refactor(docs): Explain counter suffix (#1) --- README.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 60826ff..8eda6a2 100644 --- a/README.md +++ b/README.md @@ -66,22 +66,24 @@ The _trivial_ snapshot chain by default keeps 25 snapshots, the _important_ chai Snapshots may look like so: ``` $ zfs list -o name -t all -NAME ┌─── Important because systemd -zpool snap_date_format='%F-%H%M' | is on our list of -zpool/root ▼ | important packages -zpool/root/archlinux ┌─────────────┐ ▼▼▼ -zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:imp_pkgs:systemd:bind:enchant:grep -zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:trv_pkgs:jdk17-temurin -zpool/root/archlinux@pacman_2023-03-07-0114_op:inst_sev:trv_pkgs:docker-credential-secretser... -zpool/root/archlinux@pacman_2023-03-07-0115_op:upgr_sev:trv_pkgs:proton-ge-custom-bin - ▲▲▲▲ ▲▲▲ └────────────────────────────┘ - | | Max. 30 characters per our -Pacman operation that triggered this snapshot ───┘ | pacman-zfs-snapshot.conf - | setting 'pkgs_list_max_length' -Severity based on affected packages, here trivial ───────┘ +NAME snap_date_format='%F-%H%M' ┌─── Important because systemd +zpool | | is on our list of +zpool/root ▼ ┌ Counter | important packages +zpool/root/archlinux ┌─────────────┐ ▼ ▼▼▼ +zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:imp_pkgs:systemd:bind:enchant:grep +zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:trv_pkgs:jdk17-temurin +zpool/root/archlinux@pacman_2023-03-07-0114_1_op:inst_sev:trv_pkgs:docker-credential-secretser... +zpool/root/archlinux@pacman_2023-03-07-0115_1_op:upgr_sev:trv_pkgs:proton-ge-custom-bin + ▲▲▲▲ ▲▲▲ └────────────────────────────┘ + | | Max. 30 characters per our + Pacman operation that triggered this snapshot ───┘ | pacman-zfs-snapshot.conf + | setting 'pkgs_list_max_length' + Severity based on affected packages, here trivial ───────┘ ``` -Notice how snapshot line 3 ends in `docker-credential-secretser...`. This snapshot was triggered on installation of the Arch User Repository package [docker-credential-secretservice-bin](https://aur.archlinux.org/packages/docker-credential-secretservice-bin) whose package name is 35 characters long. In this example our `pkgs_list_max_length` setting limits maximum name of the packages string to `30` characters. If we can't naturally fit package names into this limit by removing packages from the list we instead cut off part of the package name and add an ellipsis (three dots `...`). The default setting is `pkgs_list_max_length='30'`. In case the user wants three characters or fewer thus making an ellipsis impractical we simply trim the package name to that many characters: +Notice how in this case the _counter_ is `1` for all four snapshots. The counter is used as the distinguishing factor for snapshots that are otherwise identical. This avoids naming collisions by incrementing it as needed. In day-to-day operations you will typically see it at `1` as there rarely is a need to avoid collisions unless you purposely limit the timestamp length and/or package list length to the point that successive snapshots may appear identical. See [Avoiding naming collisions](#avoiding-naming-collisions) for more details. + +Notice also how snapshot line 3 ends in `docker-credential-secretser...`. This snapshot was triggered on installation of the Arch User Repository package [docker-credential-secretservice-bin](https://aur.archlinux.org/packages/docker-credential-secretservice-bin) whose package name is 35 characters long. In this example our `pkgs_list_max_length` setting limits maximum name of the packages string to `30` characters. If we can't naturally fit package names into this limit by removing packages from the list we instead cut off part of the package name and add an ellipsis (three dots `...`). The default setting is `pkgs_list_max_length='30'`. In case the user wants three characters or fewer thus making an ellipsis impractical we simply trim the package name to that many characters: ``` pkgs_list_max_length='7': dock... pkgs_list_max_length='6': doc... @@ -98,10 +100,10 @@ NAME zpool zpool/root zpool/root/archlinux -zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:imp -zpool/root/archlinux@pacman_2023-03-07-0113_op:upgr_sev:trv -zpool/root/archlinux@pacman_2023-03-07-0114_op:inst_sev:trv -zpool/root/archlinux@pacman_2023-03-07-0115_op:upgr_sev:trv +zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:imp +zpool/root/archlinux@pacman_2023-03-07-0113_1_op:upgr_sev:trv +zpool/root/archlinux@pacman_2023-03-07-0114_1_op:inst_sev:trv +zpool/root/archlinux@pacman_2023-03-07-0115_1_op:upgr_sev:trv ``` Whatever you set as your `pkgs_list_max_length` is still just a best effort as it is subject to ZFS' internal maximum for dataset name length. This limit is currently 255 characters. For a snapshot the dataset name in front of the `@` character plus everything else starting with the `@` character til the end count against the limit. If you'd like e.g. 200 characters allocated to the package list chances are that you'll see fewer characters than that depending on how long your dataset names are on their own. From 2246823d0652556e9cc501edb7f7dcf385358d9f Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 06:14:04 +0100 Subject: [PATCH 8/9] refactor(docs): Typo (#1) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8eda6a2..3ee6581 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ 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 list of packages -The script safeguards against naming collisions by adding a monotoniccally incrementing counter after the timestamp string. +The script safeguards against naming collisions by adding a monotonically 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: ``` From d606ae9688c08536320fecd664ec1f933b59e5df Mon Sep 17 00:00:00 2001 From: hygienic-books Date: Tue, 26 Dec 2023 06:15:01 +0100 Subject: [PATCH 9/9] refactor(docs): Layout (#1) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3ee6581..cdce182 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,7 @@ zpool/root/archlinux@pacman_2023-03-07-0116_2_op:upgr_sev:trv_pkgs:tmux 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. -> 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. +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. # Rollback