From 42147115fe1c8465d680267c5e50156dd5bb1ed0 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Wed, 29 Apr 2026 12:18:23 +0200 Subject: [PATCH] Update manpage --- doc/snapraid.1 | 78 +++++++++++++++++++++++++++++++------------ doc/snapraid.d | 72 +++++++++++++++++++++++++++------------ doc/snapraid.txt | 72 +++++++++++++++++++++++++++------------ snapraid.conf.example | 15 ++++++--- 4 files changed, 167 insertions(+), 70 deletions(-) diff --git a/doc/snapraid.1 b/doc/snapraid.1 index 4711e889..8fd8afb6 100644 --- a/doc/snapraid.1 +++ b/doc/snapraid.1 @@ -651,11 +651,11 @@ Print the status of the array \-> \`status\` .IP \(bu Control the disks \-> \`smart\`, \`probe\`, \`up\`, \`down\` .IP \(bu -Make a backup/snapshot \-> \`sync\` +Make a backup/recovery point \-> \`sync\` .IP \(bu Periodically check data \-> \`scrub\` .IP \(bu -Restore the last backup/snapshot \-> \`fix\`. +Restore the last backup/recovery point \-> \`fix\`. .PD .PP Commands must be written in lowercase. @@ -885,9 +885,9 @@ The files in the array are NOT modified. .SS fix Fixes all the files and the parity data. .PP -All files and parity data are compared with the snapshot -state saved in the last \`sync\`. -If a difference is found, it is reverted to the stored snapshot. +All files and parity data are compared with the state saved in +the last \`sync\`. +If a difference is found, it is reverted to the stored state. .PP WARNING! The \`fix\` command does not differentiate between errors and intentional modifications. It unconditionally reverts the file state @@ -1428,20 +1428,31 @@ Note that such disks are not affected by the \`up\` and \`down\` commands because they are expected to be always spinning. .SS snapshot Enable the use of filesystem snapshots for the \`sync\`, \`scrub\`, -\`check\`, and \`fix\` commands, provided the underlying filesystem -supports it. +\`check\`, and \`fix\` commands. +.PP +When enabled, SnapRAID creates a read\-only snapshot of your data at the +start of a \'sync\'. This ensures a consistent, point\-in\-time view of your +files, preventing errors caused by concurrent file modifications. .PP This option applies exclusively to data disks formatted with the Btrfs filesystem. Parity disks, or data disks using other filesystems, will always use the live version of the filesystem. .PP -When enabled, SnapRAID ensures atomic and consistent operations by -reading from a frozen point\-in\-time image. This prevents errors -caused by file modifications during execution and ensures that -updated and deleted files remain available for parity\-based -recovery of other disks. +This significantly improves recovery: if a file is deleted from the live +filesystem, it remains preserved in the snapshot. This prevents the parity +from becoming \[dq]broken\[dq] for that block, ensuring you can still successfully +recover data if another disk fails. .PP -See the SNAPSHOTS section for more details. +Only Btrfs is supported. Snapshots are stored in a hidden \'.snapraid\' +directory at the root of the Btrfs subvolume containing your data. +SnapRAID will automatically detect the subvolume root for each data path. +.PP +Snapshot creation and deletion require administrative privileges. +Ensure SnapRAID is run with the necessary permissions (e.g., sudo) when +this option is enabled. +.PP +See the SNAPSHOTSsection for a detailed explanation of the snapshot +lifecycle. .SS nohidden Excludes all hidden files and directories. In Unix, hidden files are those starting with \`.\`. @@ -1799,11 +1810,26 @@ If a file is updated or deleted from the live filesystem, it remains preserved in the snapshot. If a disk failure occurs before the next sync is run, SnapRAID uses the data preserved in the snapshot to reconstruct the failed disk. +.PD +.PP +.RS 4 +.PD 0 +In case of a disk failure during an active sync process, +SnapRAID is also able to read automatically from both the +snapshot of the previous parity computation and the current one. +This maximizes the probability of a full recovery by +providing access to the exact data blocks required to solve +the parity equations, even if those blocks were modified +or deleted between syncs. +.PD +.PP +.PD 0 Without snapshots, an updated or deleted file on a healthy disk results in missing data blocks that may be required to fix other failed disks. .PD .RE +.RE .PP Snapshots are created only for data disks and only if the underlying filesystem supports this functionality. Parity disks always use @@ -1812,6 +1838,10 @@ the live filesystem. At present, this is supported exclusively on Btrfs. You can mix data disks with different filesystems. Only those that support snapshots will utilize them, while other disks will continue to operate directly on the live filesystem. +.PP +Snapshot creation and deletion require administrative privileges. +Ensure SnapRAID is run with the necessary permissions (e.g., sudo) +when snapshots are enabled. .SS Command Behavior with Snapshots The \`sync\` and \`scrub\` commands both operate exclusively on snapshots to ensure that all data operations are performed against a consistent, @@ -1827,16 +1857,20 @@ point that matches the existing parity. For the \`check\` and \`fix\` commands, the use of the last snapshot depends on whether specific disks are targeted using the \-d, \-\-filter\-disk option. -Any disk explicitly selected for checking or fixing will use -the live filesystem. This allows \`check\` to verify the current state of -your files and \`fix\` to physically restore data to the active disk. .PP -All other data disks not specified by the \-d, \-\-filter\-disk option -will be accessed via their snapshots. These disks act as stable -references, providing the necessary data blocks to solve the parity -equations without interference from live changes. If no \-d option is -provided, SnapRAID assumes the operation applies to the entire array, -in this case, \`check\` and \`fix\` will use the live filesystems exclusively. +A disk explicitly selected via \-d (the \[dq]target\[dq] of the operation) +always uses the live filesystem. For \`fix\`, this allows restoring +data to the active disk replacement. For \`check\`, it allows simulating +the \`fix\` operation under the same conditions. +.PP +All other data disks (the \[dq]reference\[dq] disks) will be accessed via +their snapshots. This ensures that even if you are modifying files +on your healthy disks while a recovery is in progress, SnapRAID +has a stable, frozen reference to solve the parity equations. +.PP +If no \-d option is provided, SnapRAID assumes the operation applies +to the entire array, in this case, \`check\` and \`fix\` will use the +live filesystems exclusively. .PP All other commands operate exclusively on the live filesystem. .SH SNAPSHOTS LIFECYCLE diff --git a/doc/snapraid.d b/doc/snapraid.d index b2638d5b..ba28f521 100644 --- a/doc/snapraid.d +++ b/doc/snapraid.d @@ -388,9 +388,9 @@ Commands * Print the status of the array -> `status` * Control the disks -> `smart`, `probe`, `up`, `down` - * Make a backup/snapshot -> `sync` + * Make a backup/recovery point -> `sync` * Periodically check data -> `scrub` - * Restore the last backup/snapshot -> `fix`. + * Restore the last backup/recovery point -> `fix`. Commands must be written in lowercase. @@ -594,9 +594,9 @@ Commands fix Fixes all the files and the parity data. - All files and parity data are compared with the snapshot - state saved in the last `sync`. - If a difference is found, it is reverted to the stored snapshot. + All files and parity data are compared with the state saved in + the last `sync`. + If a difference is found, it is reverted to the stored state. WARNING! The `fix` command does not differentiate between errors and intentional modifications. It unconditionally reverts the file state @@ -1148,20 +1148,31 @@ Configuration snapshot Enable the use of filesystem snapshots for the `sync`, `scrub`, - `check`, and `fix` commands, provided the underlying filesystem - supports it. + `check`, and `fix` commands. + + When enabled, SnapRAID creates a read-only snapshot of your data at the + start of a 'sync'. This ensures a consistent, point-in-time view of your + files, preventing errors caused by concurrent file modifications. This option applies exclusively to data disks formatted with the Btrfs filesystem. Parity disks, or data disks using other filesystems, will always use the live version of the filesystem. - When enabled, SnapRAID ensures atomic and consistent operations by - reading from a frozen point-in-time image. This prevents errors - caused by file modifications during execution and ensures that - updated and deleted files remain available for parity-based - recovery of other disks. + This significantly improves recovery: if a file is deleted from the live + filesystem, it remains preserved in the snapshot. This prevents the parity + from becoming "broken" for that block, ensuring you can still successfully + recover data if another disk fails. - See the SNAPSHOTS section for more details. + Only Btrfs is supported. Snapshots are stored in a hidden '.snapraid' + directory at the root of the Btrfs subvolume containing your data. + SnapRAID will automatically detect the subvolume root for each data path. + + Snapshot creation and deletion require administrative privileges. + Ensure SnapRAID is run with the necessary permissions (e.g., sudo) when + this option is enabled. + + See the SNAPSHOTSsection for a detailed explanation of the snapshot + lifecycle. nohidden Excludes all hidden files and directories. @@ -1419,6 +1430,15 @@ Snapshots it remains preserved in the snapshot. If a disk failure occurs before the next sync is run, SnapRAID uses the data preserved in the snapshot to reconstruct the failed disk. + + In case of a disk failure during an active sync process, + SnapRAID is also able to read automatically from both the + snapshot of the previous parity computation and the current one. + This maximizes the probability of a full recovery by + providing access to the exact data blocks required to solve + the parity equations, even if those blocks were modified + or deleted between syncs. + Without snapshots, an updated or deleted file on a healthy disk results in missing data blocks that may be required to fix other failed disks. @@ -1431,6 +1451,10 @@ Snapshots support snapshots will utilize them, while other disks will continue to operate directly on the live filesystem. + Snapshot creation and deletion require administrative privileges. + Ensure SnapRAID is run with the necessary permissions (e.g., sudo) + when snapshots are enabled. + Command Behavior with Snapshots The `sync` and `scrub` commands both operate exclusively on snapshots to ensure that all data operations are performed against a consistent, @@ -1446,16 +1470,20 @@ Snapshots For the `check` and `fix` commands, the use of the last snapshot depends on whether specific disks are targeted using the -d, --filter-disk option. - Any disk explicitly selected for checking or fixing will use - the live filesystem. This allows `check` to verify the current state of - your files and `fix` to physically restore data to the active disk. - All other data disks not specified by the -d, --filter-disk option - will be accessed via their snapshots. These disks act as stable - references, providing the necessary data blocks to solve the parity - equations without interference from live changes. If no -d option is - provided, SnapRAID assumes the operation applies to the entire array, - in this case, `check` and `fix` will use the live filesystems exclusively. + A disk explicitly selected via -d (the "target" of the operation) + always uses the live filesystem. For `fix`, this allows restoring + data to the active disk replacement. For `check`, it allows simulating + the `fix` operation under the same conditions. + + All other data disks (the "reference" disks) will be accessed via + their snapshots. This ensures that even if you are modifying files + on your healthy disks while a recovery is in progress, SnapRAID + has a stable, frozen reference to solve the parity equations. + + If no -d option is provided, SnapRAID assumes the operation applies + to the entire array, in this case, `check` and `fix` will use the + live filesystems exclusively. All other commands operate exclusively on the live filesystem. diff --git a/doc/snapraid.txt b/doc/snapraid.txt index 0bb74177..dcae69ce 100644 --- a/doc/snapraid.txt +++ b/doc/snapraid.txt @@ -412,9 +412,9 @@ SnapRAID provides a few simple commands that allow you to: * Print the status of the array -> `status` * Control the disks -> `smart`, `probe`, `up`, `down` -* Make a backup/snapshot -> `sync` +* Make a backup/recovery point -> `sync` * Periodically check data -> `scrub` -* Restore the last backup/snapshot -> `fix`. +* Restore the last backup/recovery point -> `fix`. Commands must be written in lowercase. @@ -636,9 +636,9 @@ The files in the array are NOT modified. Fixes all the files and the parity data. -All files and parity data are compared with the snapshot -state saved in the last `sync`. -If a difference is found, it is reverted to the stored snapshot. +All files and parity data are compared with the state saved in +the last `sync`. +If a difference is found, it is reverted to the stored state. WARNING! The `fix` command does not differentiate between errors and intentional modifications. It unconditionally reverts the file state @@ -1226,20 +1226,31 @@ because they are expected to be always spinning. ------------ Enable the use of filesystem snapshots for the `sync`, `scrub`, -`check`, and `fix` commands, provided the underlying filesystem -supports it. +`check`, and `fix` commands. + +When enabled, SnapRAID creates a read-only snapshot of your data at the +start of a 'sync'. This ensures a consistent, point-in-time view of your +files, preventing errors caused by concurrent file modifications. This option applies exclusively to data disks formatted with the Btrfs filesystem. Parity disks, or data disks using other filesystems, will always use the live version of the filesystem. -When enabled, SnapRAID ensures atomic and consistent operations by -reading from a frozen point-in-time image. This prevents errors -caused by file modifications during execution and ensures that -updated and deleted files remain available for parity-based -recovery of other disks. +This significantly improves recovery: if a file is deleted from the live +filesystem, it remains preserved in the snapshot. This prevents the parity +from becoming "broken" for that block, ensuring you can still successfully +recover data if another disk fails. -See the SNAPSHOTS section for more details. +Only Btrfs is supported. Snapshots are stored in a hidden '.snapraid' +directory at the root of the Btrfs subvolume containing your data. +SnapRAID will automatically detect the subvolume root for each data path. + +Snapshot creation and deletion require administrative privileges. +Ensure SnapRAID is run with the necessary permissions (e.g., sudo) when +this option is enabled. + +See the SNAPSHOTSsection for a detailed explanation of the snapshot +lifecycle. 7.8 nohidden ------------ @@ -1524,6 +1535,15 @@ Recovery - If a file is updated or deleted from the live filesystem, it remains preserved in the snapshot. If a disk failure occurs before the next sync is run, SnapRAID uses the data preserved in the snapshot to reconstruct the failed disk. + + In case of a disk failure during an active sync process, + SnapRAID is also able to read automatically from both the + snapshot of the previous parity computation and the current one. + This maximizes the probability of a full recovery by + providing access to the exact data blocks required to solve + the parity equations, even if those blocks were modified + or deleted between syncs. + Without snapshots, an updated or deleted file on a healthy disk results in missing data blocks that may be required to fix other failed disks. @@ -1536,6 +1556,10 @@ You can mix data disks with different filesystems. Only those that support snapshots will utilize them, while other disks will continue to operate directly on the live filesystem. +Snapshot creation and deletion require administrative privileges. +Ensure SnapRAID is run with the necessary permissions (e.g., sudo) +when snapshots are enabled. + 8.1 Command Behavior with Snapshots ----------------------------------- @@ -1553,16 +1577,20 @@ point that matches the existing parity. For the `check` and `fix` commands, the use of the last snapshot depends on whether specific disks are targeted using the -d, --filter-disk option. -Any disk explicitly selected for checking or fixing will use -the live filesystem. This allows `check` to verify the current state of -your files and `fix` to physically restore data to the active disk. -All other data disks not specified by the -d, --filter-disk option -will be accessed via their snapshots. These disks act as stable -references, providing the necessary data blocks to solve the parity -equations without interference from live changes. If no -d option is -provided, SnapRAID assumes the operation applies to the entire array, -in this case, `check` and `fix` will use the live filesystems exclusively. +A disk explicitly selected via -d (the "target" of the operation) +always uses the live filesystem. For `fix`, this allows restoring +data to the active disk replacement. For `check`, it allows simulating +the `fix` operation under the same conditions. + +All other data disks (the "reference" disks) will be accessed via +their snapshots. This ensures that even if you are modifying files +on your healthy disks while a recovery is in progress, SnapRAID +has a stable, frozen reference to solve the parity equations. + +If no -d option is provided, SnapRAID assumes the operation applies +to the entire array, in this case, `check` and `fix` will use the +live filesystems exclusively. All other commands operate exclusively on the live filesystem. diff --git a/snapraid.conf.example b/snapraid.conf.example index 2c8a8660..f3d8649f 100644 --- a/snapraid.conf.example +++ b/snapraid.conf.example @@ -50,18 +50,25 @@ extra boot / # start of a 'sync'. This ensures a consistent, point-in-time view of your # files, preventing errors caused by concurrent file modifications. # +# This option applies exclusively to data disks formatted with the Btrfs +# filesystem. Parity disks, or data disks using other filesystems, will +# always use the live version of the filesystem. +# # This significantly improves recovery: if a file is deleted from the live # filesystem, it remains preserved in the snapshot. This prevents the parity # from becoming "broken" for that block, ensuring you can still successfully # recover data if another disk fails. # # Only Btrfs is supported. Snapshots are stored in a hidden '.snapraid' -# directory at the root of each data subvolume. +# directory at the root of the Btrfs subvolume containing your data. +# SnapRAID will automatically detect the subvolume root for each data path. # -# Two snapshots are managed per disk: -# .snapraid/pending - The snapshot currently being processed. -# .snapraid/stable - The last successfully completed sync state. +# Snapshot creation and deletion require administrative privileges. +# Ensure SnapRAID is run with the necessary permissions (e.g., sudo) when +# this option is enabled. # +# See the 'Snapshots' section in the snapraid(1) manpage for a detailed +# explanation of the snapshot lifecycle. #snapshot # Excludes hidden files and directories (uncomment to enable).