Merge tag 'v0.32.7'

Merge branch created for security release v0.32.7 back to master.

Contains fix for CVE-2026-62943, along with cherry-picked minor
bugfixes.

.github/workflows/codespell.yml

@@ -0,0 +1,26 @@
+---
+name: Codespell
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2
+        with:
+          check_filenames: true
+          skip: ".git,*.pdf,*.svg"
+          ignore_words_list: uptodate

ChangeLog

@@ -61,7 +61,7 @@ btrbk-0.32.1
 btrbk-0.32.0
 
   * MIGRATION
-    - If timestamp_format is not configured, explicitely set
+    - If timestamp_format is not configured, explicitly set
       "timestamp_format short" to revert old behavior.
     - Update ssh_filter_btrbk.sh on remote hosts.
   * Change default for timestamp_format to "long".
@@ -95,7 +95,7 @@ btrbk-0.31.2
   * MIGRATION
     - Update ssh_filter_btrbk.sh on remote hosts.
   * ssh_filter_btrbk.sh: Fix security vulnerability.
-    Specialy crafted commands may be executed without being propely
+    Specially crafted commands may be executed without being properly
     checked. Applies to remote hosts filtering ssh commands using
     ssh_filter_btrbk.sh in authorized_keys.
   * Warn if no subvolume defined in config (close #378).
@@ -262,7 +262,7 @@ btrbk-0.27.0
     - Allow snapshot_dir to be a mountpoint.
     - Search complete target tree for correlated subvolumes.
     - Include snapshots from all mountpoints as candidates (disabled
-      due to uptream bug: github.com/kdave/btrfs-progs/issues/96).
+      due to upstream bug: github.com/kdave/btrfs-progs/issues/96).
     - Read /proc/self/mountinfo instead of /proc/self/mounts.
     - Always read /proc/self/mountinfo.
     - Resolve realpath using readlink(1).
@@ -333,7 +333,7 @@ btrbk-0.25.0
   * Allow trailing comments in btrbk.conf (close #129).
   * Bugfix: rate limiting must be done after compression (close #134).
   * raw_target_encrypt: Always set "gpg --no-random-seed-file":
-    prevents creation of "~/.gnupg/random_seed" with slight perfomance
+    prevents creation of "~/.gnupg/random_seed" with slight performance
     penalty.
 
 btrbk-0.24.0

contrib/crypt/kdf_pbkdf2.py

@@ -54,7 +54,7 @@ salt_hex = "".join(["{:02x}".format(x) for x in salt])
 dk_hex = "".join(["{:02x}".format(x) for x in dk])
 
 print("KEY=" + dk_hex);
-print("algoritm=pbkdf2_hmac");
+print("algorithm=pbkdf2_hmac");
 print("hash_name=" + hash_name);
 print("salt=" + salt_hex);
 print("iterations=" + str(iterations));

contrib/tools/btrbk_restore_raw.py

@@ -196,7 +196,7 @@ def main():
     parser.add_argument('restore_dir', help="target directory for restored subvolumes"
                                             " (path argument for \"btrfs receive\")")
     parser.add_argument('-n', '--dry-run', action='store_true',
-                        help="print commmands that would be executed")
+                        help="print commands that would be executed")
     parser.add_argument('--ignore-missing', action='store_true',
                         help="do not fail on missing parent snapshots")
 

doc/Makefile

@@ -1,5 +1,4 @@
-DOCS       = FAQ.md \
+DOCS       = FAQ.md
-             upgrade_to_v0.23.0.md
 MAN_MAN1   = btrbk.1 \
              lsbtr.1 \
              ssh_filter_btrbk.1
@@ -18,8 +17,19 @@ ifeq ($(COMPRESS), yes)
 endif
 
 # convert using "asciidoctor": <https://asciidoctor.org>
-ASCIIDOCTOR_MANPAGE = asciidoctor -d manpage -b manpage
+# fallback to "a2x" from asciidoc package: <http://asciidoc.org>
-ASCIIDOCTOR_HTML    = asciidoctor -b html5 -d article
+ifneq (, $(shell command -v asciidoctor 2> /dev/null))
+  ASCIIDOC_MANPAGE = asciidoctor -d manpage -b manpage
+  ASCIIDOC_HTML    = asciidoctor -b html5 -d article
+else ifneq (, $(shell command -v a2x 2> /dev/null))
+  # NOTE: using -L (--no-xmllint), as xmllint is a separate package on many distros.
+  ASCIIDOC_MANPAGE = a2x -L -d manpage -f manpage
+  ASCIIDOC_HTML    = asciidoc -b html -d article
+else
+  ASCIIDOC_ERR = $(error "please install either asciidoc or asciidoctor")
+  ASCIIDOC_MANPAGE = $(ASCIIDOC_ERR)
+  ASCIIDOC_HTML    = $(ASCIIDOC_ERR)
+endif
 
 # reproducible builds: reference date is ":date:" attribute from asciidoc source
 date_attr = $(shell sed -rn 's/:date:\s*//p' $(1))
@@ -50,10 +60,10 @@ clean:
 	gzip -9 -n -c $< > $@
 
 %.1 : %.1.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_MANPAGE) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_MANPAGE) $<
 
 %.5 : %.5.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_MANPAGE) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_MANPAGE) $<
 
 %.html : %.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_HTML) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_HTML) -o $@ $<

doc/btrbk.1.asciidoc

@@ -88,8 +88,15 @@ OPTIONS
     commands that would be executed.
 
 --exclude <filter>::
-    Exclude configured sections matching '<filter>'. See
+    Exclude configured sections matching '<filter>' (see
-    <<_filter_statements,FILTER STATEMENTS>> below.
+    <<_filter_statements,FILTER STATEMENTS>> below), or any specific
+    snapshot from being backuped or deleted, or any specific backup
+    from being deleted.
++
+Note that excluding specific snapshots from being backuped has impact
+on scheduling: e.g. if the "first snapshot of the day" is excluded,
+the "second snapshot of the day" shifts to "first", creating a backup
+as "first backup of the day".
 
 -p, --preserve::
     Preserve all snapshots and backups. Skips deletion of any

doc/btrbk.conf.5.asciidoc

@@ -605,10 +605,6 @@ TARGET TYPES
     btrfs-send(8), with optional compression and encryption.
 +
 --
-Note that the target preserve mechanism is currently disabled for
-incremental raw backups (btrbk does not delete any incremental raw
-files)!
-
 Raw backups consist of two files: the main data file containing the
 btrfs send stream, and a sidecar file ".info" containing metadata:
 
@@ -624,6 +620,11 @@ For 'incremental' backups ("incremental yes"), please note that:
   make sure that a non-incremental backup is triggered from time to
   time.
 
+* The scheduler will never delete dependent parents of backups
+  preserved by the retention policy (run btrbk with the '-S',
+  '--print-schedule' option to get a comprehensive output of the
+  scheduler results).
+
 * There is currently no support for rotation of incremental backups:
   if 'incremental' is set, a full backup must be triggered manually
   from time to time in order to be able to delete old backups.

doc/install.md

@@ -9,7 +9,8 @@ file, choose one of the following methods:
 
 ### Generic Linux System
 
-Install [asciidoctor] if you want to build the documentation.
+Install [asciidoctor] or [asciidoc] if you want to build the
+documentation.
 
 Download and unpack the latest [btrbk source tarball] and type:
 
@@ -64,3 +65,4 @@ btrbk is in Void's `current` repository
 
   [btrbk source tarball]: https://digint.ch/download/btrbk/releases/
   [asciidoctor]: https://asciidoctor.org
+  [asciidoc]: https://asciidoc.org

doc/upgrade_to_v0.23.0.md

@@ -1,92 +0,0 @@
-Upgrading to btrbk-v0.23.0
-==========================
-
-In order to keep btrbk simple and intuitive while adding new features,
-it became inevitable to change the semantics of the "retention policy"
-related configuration options.
-
-
-What has changed?
------------------
-
-### Preserve *first* instead of *last* snapshot/backup
-
-btrbk used to *always* transfer the latest snapshot to the target
-location, while considering the *last* snapshot/backup of a day as a
-daily backup (and also the last weekly as a monthly). This made it
-very cumbersome when running btrbk in a cron job as well as manually,
-because the last manually created snapshot was immediately transferred
-on every run, and used as the daily backup (instead of the one created
-periodically by the cron job).
-
-The new semantics are to consider the *first* (instead of *last*)
-snapshot of a hour/day/week/month as the one to be preserved, while
-only transferring the snapshots needed to satisfy the target retention
-policy.
-
-
-### Preserve snapshots for a minimum amount of time
-
-In order to specify a minimum amount of time in which *all* snapshots
-should be preserved, the new "snapshot_preserve_min" and
-"target_preserve_min" configuration options were introduced. This was
-previously covered by "snapshot_preserve_daily", which caused a lot of
-confusion among users.
-
-
-Upgrading the configuration file: /etc/btrbk/btrbk.conf
--------------------------------------------------------
-
-Please read the description of the "run" command in [btrbk(1)], as
-well as the "RETENTION POLICY" section in [btrbk.conf(5)] for a
-detailed description. Make sure to understand the new concept, and run
-`btrbk --print-schedule dryrun` after updating the configuration.
-
-
-### Upgrade retention policy
-
-If you want the same behaviour as before:
-
-    # replace this:
-    snapshot_preserve_daily   <daily>
-    snapshot_preserve_weekly  <weekly>
-    snapshot_preserve_monthly <monthly>
-
-    # with:
-    snapshot_preserve_min  <daily>d
-    snapshot_preserve      <weekly>w <monthly>m
-
-    # ... do the same with "target_preserve_*" options
-
-
-But what you probably want is something like:
-
-    snapshot_preserve_min  5d
-    snapshot_preserve      <daily>d <weekly>w <monthly>m
-
-    target_preserve_min    no
-    target_preserve        <daily>d <weekly>w <monthly>m *y
-
-This states:
-
-  * Keep all snapshots for five days (no matter how many there are)
-  * Transfer only the first snapshot of a day to the target
-  * Keep all "first snapshots of a day" for `<daily>` days, etc.
-
-
-### Upgrade "resume_missing"
-
-If you have a line: "resume_missing yes" somwhere in your config,
-simply remove it. btrbk always resumes missing backups.
-
-If you have "resume_missing no", you can imitate this behaviour by
-setting:
-
-    target_preserve_min  latest
-    target_preserve      no
-
-This states: "always transfer the latest snapshot to the target".
-
-
-  [btrbk(1)]: https://digint.ch/btrbk/doc/btrbk.1.html
-  [btrbk.conf(5)]: https://digint.ch/btrbk/doc/btrbk.conf.5.html