.github/workflows/codespell.yml

@@ -1,26 +0,0 @@
----
-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

@@ -47,7 +47,7 @@ btrbk-0.32.1
 btrbk-0.32.0
 
   * MIGRATION
-    - If timestamp_format is not configured, explicitly set
+    - If timestamp_format is not configured, explicitely set
       "timestamp_format short" to revert old behavior.
     - Update ssh_filter_btrbk.sh on remote hosts.
   * Change default for timestamp_format to "long".
@@ -81,7 +81,7 @@ btrbk-0.31.2
   * MIGRATION
     - Update ssh_filter_btrbk.sh on remote hosts.
   * ssh_filter_btrbk.sh: Fix security vulnerability.
-    Specially crafted commands may be executed without being properly
+    Specialy crafted commands may be executed without being propely
     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).
@@ -248,7 +248,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 upstream bug: github.com/kdave/btrfs-progs/issues/96).
+      due to uptream 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).
@@ -319,7 +319,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 performance
+    prevents creation of "~/.gnupg/random_seed" with slight perfomance
     penalty.
 
 btrbk-0.24.0

README.md

@@ -428,7 +428,7 @@ host. For each backup, two files are created:
   * `/backup/home.YYYYMMDD.btrfs.xz.gpg.info`: sidecar file containing
     metadata used by btrbk.
 
-If you are using raw _incremental_ backups, please make sure you
+I you are using raw _incremental_ backups, please make sure you
 understand the implications (see [btrbk.conf(5)], TARGET TYPES).
 
 

contrib/cron/btrbk-mail

@@ -4,9 +4,6 @@
 
 now=$(date +%Y%m%d)
 
-declare -A rsync_src rsync_dst rsync_log rsync_rsh rsync_opt
-declare -A sync_fs_onchange
-
 #####  start config section  #####
 
 # Email recipients, separated by whitespace:
@@ -33,9 +30,7 @@ rsync_opt[example_data]="-az --delete --inplace --numeric-ids --acls --xattrs"
 # If set, add "rsync_dst" to "sync_fs" (see below) if rsync reports files transferred
 #sync_fs_onchange[example_data]=yes
 
-# Enable all rsync declarations (all indices of rsync_src array)
+# Enabled rsync declarations (whitespace-separated list)
-#rsync_enable=${!rsync_src[@]}
-# Explicitly enable rsync declarations (whitespace-separated list)
 #rsync_enable="example_data"
 rsync_enable=
 

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("algorithm=pbkdf2_hmac");
+print("algoritm=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 commands that would be executed")
+                        help="print commmands that would be executed")
     parser.add_argument('--ignore-missing', action='store_true',
                         help="do not fail on missing parent snapshots")
 

doc/Makefile

@@ -1,4 +1,5 @@
-DOCS       = FAQ.md
+DOCS       = FAQ.md \
+             upgrade_to_v0.23.0.md
 MAN_MAN1   = btrbk.1 \
              lsbtr.1 \
              ssh_filter_btrbk.1
@@ -17,19 +18,8 @@ ifeq ($(COMPRESS), yes)
 endif
 
 # convert using "asciidoctor": <https://asciidoctor.org>
-# fallback to "a2x" from asciidoc package: <http://asciidoc.org>
+ASCIIDOCTOR_MANPAGE = asciidoctor -d manpage -b manpage
-ifneq (, $(shell command -v asciidoctor 2> /dev/null))
+ASCIIDOCTOR_HTML    = asciidoctor -b html5 -d article
-  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))
@@ -60,10 +50,10 @@ clean:
 	gzip -9 -n -c $< > $@
 
 %.1 : %.1.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_MANPAGE) $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_MANPAGE) -o $@ $<
 
 %.5 : %.5.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_MANPAGE) $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_MANPAGE) -o $@ $<
 
 %.html : %.asciidoc
-	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOC_HTML) -o $@ $<
+	SOURCE_DATE_EPOCH=$(call source_date_epoch,$<) $(ASCIIDOCTOR_HTML) -o $@ $<

doc/btrbk.1.asciidoc

@@ -88,15 +88,8 @@ 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), or any specific
+    <<_filter_statements,FILTER STATEMENTS>> below.
-    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
@@ -143,7 +136,7 @@ as "first backup of the day".
     space-separated, quoted key=value pairs (machine readable).
 +
 If set to "col:", prints only the <columns> specified (comma-separated
-list). Header lines are omitted if the "h:" modifier is present.
+list). Header lines are ommitted if the "h:" modifier is present.
 Columns prefixed with "-" are collapsed if empty. Columns postfixed
 with ":RALIGN" are right-aligned.
 
@@ -161,9 +154,9 @@ with ":RALIGN" are right-aligned.
     command (version >= 20180505) installed on the host running btrbk.
 
 --lockfile <file>::
-    Place an exclusive lock on <file> during program execution, using
+    Create lockfile <file> on startup; checks lockfile before running
-    flock(2). If the lock is held by another process, exit before
+    any btrfs commands (using perl "flock"), and exits if the lock is
-    running any actions. Overrides configuration option
+    held by another btrbk instance. Overrides configuration option
     "lockfile". Ignored on dryrun ('-n', '--dry-run').
 
 --override <config_option>=<value>::

doc/btrbk.conf.5.asciidoc

@@ -291,9 +291,9 @@ set to ``all'' (the default).
     Number of threads to use for <compress_command>. Only supported
     for "pigz", "pbzip2", "bzip3", "zstd" and recent versions of "xz".
 
-*stream_compress_adapt* yes|no::
+*stream_compress_adapt* default|<number>::
     Enable adaptive compression for <compress_command>. Only supported
-    for "zstd" (version >= 1.3.6). Defaults to ``no''.
+    for "zstd" (version >= 1.3.6).
 
 *stream_buffer* <size>|no::
     Add a buffer to the btrfs send stream (locally, on uncompressed
@@ -359,10 +359,10 @@ constraints.
     daemon, auth, lpr, news, cron, authpriv, local0..local7.
 
 *lockfile* <file>|no::
-    Place an exclusive lock on <file> during program execution, using
+    Create lockfile <file> on startup; checks lockfile before running
-    flock(2). If the lock is held by another process, exit before
+    any btrfs commands (using perl "flock"), and exits if the lock is
-    running any actions. Ignored on dryrun ('-n', '--dry-run'). See
+    held by another btrbk instance. Ignored on dryrun ('-n',
-    also '--lockfile' command-line option.
+    '--dry-run'). See also '--lockfile' command-line option.
 
 *backend* <backend>::
     Backend filesystem utilities to be used for btrfs specific
@@ -605,6 +605,10 @@ 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:
 
@@ -620,11 +624,6 @@ 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,8 +9,7 @@ file, choose one of the following methods:
 
 ### Generic Linux System
 
-Install [asciidoctor] or [asciidoc] if you want to build the
+Install [asciidoctor] if you want to build the documentation.
-documentation.
 
 Download and unpack the latest [btrbk source tarball] and type:
 
@@ -65,4 +64,3 @@ 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/lsbtr.1.asciidoc

@@ -67,7 +67,7 @@ OPTIONS
     space-separated key="value" pairs (machine readable).
 +
 If set to "col:", prints only the <columns> specified (comma-separated
-list). Header lines are omitted if the "h:" modifier is present.
+list). Header lines are ommitted if the "h:" modifier is present.
 Columns prefixed with "-" are collapsed if empty. Columns postfixed
 with ":RALIGN" are right-aligned.
 

doc/upgrade_to_v0.23.0.md

@@ -0,0 +1,92 @@
+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