nixos/btrbk: add snapshotOnly option

[cything]

Things done

Added snapshotOnly option that is useful to people who use btrbk to send incremental snapshot backups to an external drive. Upstream has this use case documented here.

Using snapshot subcommand instead of run makes btrbk skip backup creation and deletion steps which can later be run manually with btrbk resume. With run, the service would fail if the external drive is not mounted.

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[rhendric]

Would you please add btrbk(1) to doc/manpage-urls.json? Otherwise, looks good to me!

[cything]

Would you please add btrbk(1) to doc/manpage-urls.json? Otherwise, looks good to me!

Done!
Upstream links to this URL here

[rhendric]

Going to wait for @oxalica to look at this, but if they don't get back to you in a week or so you can ping me for a merge.

[oxalica]

Going to wait for @oxalica to look at this

I don't have a strong opinion on this. I have a dedicated .conf for snapshot-only purpose (with a different cleanup policy) so I don't "need" this change personally. But I think it's worth to have option changing the btrbk verb.

[oxalica]

This option toggles between "snapshot" and "run" subcommand, thus preventing us from adding/using subcommand other than these two. Will "resume" or "prune" also be helpful in some cases? If so, we should add a "subcommand" option which defaults to "run" instead.

[cything]

I can't think of an example where someone might want to run resume or prune as a service. resume will prune according to the configured retention policy after it's done backing up just like snapshot. You can't only use resume on its own either since btrbk compares against snapshots instead of source during the backup stage meaning snapshot has to have run before to create snapshots that haven't been backed up yet.

[oxalica]

Okay, I'm convinced.

[ayyess]

Wouldn't snapshot --preserve be more "useful to people who use btrbk to send incremental snapshot backups to an external drive"? snapshot on its own will still delete local snapshots according to the table in https://digint.ch/btrbk/doc/btrbk.1.html. Exposing a subcommand and args list might be more extendable than a single snapshotOnly attribute.

[cything]

snapshot will delete local snapshots according to snapshot_preserve and snapshot_preserve_min which is the same behavior as run. If you don't want snapshots to be deleted at all you could set snapshot_preserve_min to all. Retention policy for backups is configured with target_preserve and target_preserve_min. I would assume that people would want their backups to last longer than local snapshots hence they can set different retention policies.

Also, snapshot will not delete any snapshots that are yet to be backed up to the target despite what the retention policy may imply.