From d830a923427720fecef65e30fdf6be302a1e7669 Mon Sep 17 00:00:00 2001 From: ibizaman Date: Mon, 27 Apr 2026 23:09:16 +0200 Subject: [PATCH] sanoid: fix doc --- docs/blocks.md | 4 ++ docs/redirects.json | 57 +++++++++++++++++++++++++++ modules/blocks/sanoid/docs/default.md | 23 ++++++++--- 3 files changed, 78 insertions(+), 6 deletions(-) diff --git a/docs/blocks.md b/docs/blocks.md index c31dc6b..efa2a6e 100644 --- a/docs/blocks.md +++ b/docs/blocks.md @@ -31,6 +31,10 @@ modules/blocks/borgbackup/docs/default.md modules/blocks/restic/docs/default.md ``` +```{=include=} chapters html:into-file=//blocks-sanoid.html +modules/blocks/sanoid/docs/default.md +``` + ## Database {#blocks-category-database} ```{=include=} chapters html:into-file=//blocks-postgresql.html diff --git a/docs/redirects.json b/docs/redirects.json index 133d3f8..5e46c8e 100644 --- a/docs/redirects.json +++ b/docs/redirects.json @@ -1604,6 +1604,63 @@ "blocks-restic-usage-provider-remote": [ "blocks-restic.html#blocks-restic-usage-provider-remote" ], + "blocks-sanoid": [ + "blocks-sanoid.html#blocks-sanoid" + ], + "blocks-sanoid-contract-provider": [ + "blocks-sanoid.html#blocks-sanoid-contract-provider" + ], + "blocks-sanoid-options": [ + "blocks-sanoid.html#blocks-sanoid-options" + ], + "blocks-sanoid-options-shb.sanoid.backup": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request.excludePatterns": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request.excludePatterns" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request.hooks": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request.hooks" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request.hooks.afterBackup": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request.hooks.afterBackup" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request.hooks.beforeBackup": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request.hooks.beforeBackup" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request.sourceDirectories": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request.sourceDirectories" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.request.user": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.request.user" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.result": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.result" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.result.backupService": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.result.backupService" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.result.restoreScript": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.result.restoreScript" + ], + "blocks-sanoid-options-shb.sanoid.backup._name_.settings": [ + "blocks-sanoid.html#blocks-sanoid-options-shb.sanoid.backup._name_.settings" + ], + "blocks-sanoid-usage": [ + "blocks-sanoid.html#blocks-sanoid-usage" + ], + "blocks-sanoid-usage-custom-template": [ + "blocks-sanoid.html#blocks-sanoid-usage-custom-template" + ], + "blocks-sanoid-usage-default-template": [ + "blocks-sanoid.html#blocks-sanoid-usage-default-template" + ], + "blocks-sanoid-usage-without-contract": [ + "blocks-sanoid.html#blocks-sanoid-usage-without-contract" + ], "blocks-sops": [ "blocks-sops.html#blocks-sops" ], diff --git a/modules/blocks/sanoid/docs/default.md b/modules/blocks/sanoid/docs/default.md index a71e0f8..02709e0 100644 --- a/modules/blocks/sanoid/docs/default.md +++ b/modules/blocks/sanoid/docs/default.md @@ -14,10 +14,10 @@ Defined in [`/modules/blocks/sanoid.nix`](@REPO@/modules/blocks/sanoid.nix): This block provides the following contracts: -- [backup contract](contracts-backup.html) under the [`shb.sanoid.backup`][backup] option. +- [dataset backup contract](contracts-datasetbackup.html) under the [`shb.sanoid.backup`][backup] option. It is tested with the [generic contract tests][backup contract tests]. -[backup]: #blocks-sanoid-options-shb.restic.backup +[backup]: #blocks-sanoid-options-shb.sanoid.backup [backup contract tests]: @REPO@/test/contracts/backup.nix ## Usage {#blocks-sanoid-usage} @@ -34,10 +34,14 @@ Backup a dataset using the default Sanoid template: path = "/home"; }; - shb.sanoid.backup."root/home" = { }; + shb.sanoid.backup."root/home" = { + request = shb.zfs.pools.root.datasets.home.datasetBackup.request; + }; } ``` +This uses the dataset backup contract which is exposed through the ZFS module's [`shb.zfs.pools..datasets..datasetBackup`](blocks-zfs.html#blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.datasetbackup) option. + ### Custom Template {#blocks-sanoid-usage-custom-template} Create a custom template and use it: @@ -56,6 +60,7 @@ Create a custom template and use it: }; shb.sanoid.backup."root/home" = { + request = shb.zfs.pools.root.datasets.home.datasetBackup.request; template = "yearly"; }; } @@ -63,9 +68,10 @@ Create a custom template and use it: Note we use the upstream `services.sanoid.templates` option to define the templates. -### Custom Template {#blocks-sanoid-usage-custom-template} +### Without contract {#blocks-sanoid-usage-without-contract} -Create a custom template and use it: +To backup a dataset that does not provide the dataset backup contract, +we can just set the request manually: ```nix { @@ -73,10 +79,15 @@ Create a custom template and use it: path = "/home"; }; - shb.sanoid.backup."root/home"; + shb.sanoid.backup."root/home" = { + request.dataset = "root/home"; + }; } ``` +Note the attr name under the `shb.sanoid.backup` option does not +set the dataset name. + ## Options Reference {#blocks-sanoid-options} ```{=include=} options