From e5151deb29518dc2bd5d2e2a27d6cbbbf56ae325 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Tue, 29 Mar 2011 18:57:13 +0200 Subject: [PATCH] More documentation. --- snapraid.1 | 56 +++++++++++++++++++++++++++++++++++++------------- snapraid.d | 58 ++++++++++++++++++++++++++++++++++++++-------------- snapraid.txt | 56 +++++++++++++++++++++++++++++++++++++------------- 3 files changed, 127 insertions(+), 43 deletions(-) diff --git a/snapraid.1 b/snapraid.1 index 12ac6220..e739ce45 100644 --- a/snapraid.1 +++ b/snapraid.1 @@ -222,19 +222,31 @@ Restore the last backup/snapshot \(hy> \(a"fix\(a". .B sync Updates the redundancy information. All the modified files in the disk array are read, and the redundancy data is -updated. +recomputed. +Files are identified by inode and checked by time and size, +meaning that you can move them on the disk without triggering +any redundancy recomputation. You can stop this process at any time pressing Ctrl+C, without losing the work already done. +The \(a"content\(a" and \(a"parity\(a" files are modified if necessary. +The files in the array are NOT modified. .TP .B check -Checks all the files the redundancy data. All the files -are hashed and compared with the snapshot saved in the -previous \(a"sync\(a" command. +Checks all the files and the redundancy data. +All the files are hashed and compared with the snapshot saved +in the previous \(a"sync\(a" command. +Files are identified by path, and checked by content. +Nothing is modified. .TP .B fix Checks and fix all the files. It\(cqs like \(a"check\(a" but it also tries to fix problems reverting the state of the disk array at the previous \(a"sync\(a" command. +After a successful \(a"fix\(a", you should also run a \(a"sync\(a" +command to update the new state of the files. +The \(a"content\(a" file is NOT modified. +The \(a"parity\(a" file is modified if necessary. +The files in the array are modified if necessary. .SH OPTIONS .TP .B \(hyc, \(hy\(hyconf CONFIG @@ -447,10 +459,15 @@ exclude tmp/ .PD .RE .SH CONTENT -SnapRAID creates a content file describing the content of your disk array. +SnapRAID creates a content file describing the content of your disk +array. .PP -You should never change it manually, although the format of this file is -described here. +It\(cqs a text file, listing all the files in your disk array. +.PP +This file is read and written by the \(a"sync\(a" command, and only read by +\(a"fix\(a" and \(a"check\(a". +You should never change it manually, although the format of this file +is described here. .TP .B blk_size SIZE Defines the size of the block in bytes. It must match the size @@ -473,17 +490,28 @@ BLOCK is the block position in the \(a"parity\(a" file. 0 for the first block, 1 for the second one and so on. HASH is the md5 of the block. In the last block of the file, the HASH is the hash of only the used part of the block. +.TP +.B inv BLOCK [HASH] +Like \(a"blk\(a", but inform that the parity of this block is invalid. +The HASH may be missing if not yet computed. +This field is used only when you interrupt manually the \(a"sync\(a" +command. .SH PARITY -SnapRAID creates a parity file containing the parity information of your disk array. +SnapRAID creates a parity file containing the redundancy information +of your disk array. .PP -It\(cqs a binary file, containing the parity information of all the blocks defined -in the \(a"content\(a" file. +It\(cqs a binary file, containing the computed parity of all the blocks +defined in the \(a"content\(a" file. .PP -For all the blocks at a given position, the parity information is computed with -the XOR operator applied to all the blocks. +This file is read and written by the \(a"sync\(a" and \(a"fix\(a" commands, and +only read by \(a"check\(a". .PP -When a file block is shorter than the default block size, for example because it\(cqs -the last block of a file, it\(cqs assumed filled with 0 at the end in the XOR operation. +For all the blocks at a given position, the parity information is +computed with the XOR operator applied to all the blocks. +.PP +When a file block is shorter than the default block size, for example +because it\(cqs the last block of a file, it\(cqs assumed as filled with 0 +at the end. .SH COPYRIGHT This file is Copyright (C) 2011 Andrea Mazzoleni .SH SEE ALSO diff --git a/snapraid.d b/snapraid.d index 4621600d..b304142d 100644 --- a/snapraid.d +++ b/snapraid.d @@ -137,19 +137,31 @@ Commands =sync Updates the redundancy information. All the modified files in the disk array are read, and the redundancy data is - updated. + recomputed. + Files are identified by inode and checked by time and size, + meaning that you can move them on the disk without triggering + any redundancy recomputation. You can stop this process at any time pressing Ctrl+C, without losing the work already done. + The "content" and "parity" files are modified if necessary. + The files in the array are NOT modified. =check - Checks all the files the redundancy data. All the files - are hashed and compared with the snapshot saved in the - previous "sync" command. + Checks all the files and the redundancy data. + All the files are hashed and compared with the snapshot saved + in the previous "sync" command. + Files are identified by path, and checked by content. + Nothing is modified. =fix Checks and fix all the files. It's like "check" but it also tries to fix problems reverting the state of the disk array at the previous "sync" command. + After a successful "fix", you should also run a "sync" + command to update the new state of the files. + The "content" file is NOT modified. + The "parity" file is modified if necessary. + The files in the array are modified if necessary. Options -c, --conf CONFIG @@ -306,10 +318,15 @@ Pattern :exclude tmp/ Content - SnapRAID creates a content file describing the content of your disk array. + SnapRAID creates a content file describing the content of your disk + array. - You should never change it manually, although the format of this file is - described here. + It's a text file, listing all the files in your disk array. + + This file is read and written by the "sync" command, and only read by + "fix" and "check". + You should never change it manually, although the format of this file + is described here. =blk_size SIZE Defines the size of the block in bytes. It must match the size @@ -333,17 +350,28 @@ Content HASH is the md5 of the block. In the last block of the file, the HASH is the hash of only the used part of the block. + =inv BLOCK [HASH] + Like "blk", but inform that the parity of this block is invalid. + The HASH may be missing if not yet computed. + This field is used only when you interrupt manually the "sync" + command. + Parity - SnapRAID creates a parity file containing the parity information of your disk array. + SnapRAID creates a parity file containing the redundancy information + of your disk array. - It's a binary file, containing the parity information of all the blocks defined - in the "content" file. - - For all the blocks at a given position, the parity information is computed with - the XOR operator applied to all the blocks. + It's a binary file, containing the computed parity of all the blocks + defined in the "content" file. - When a file block is shorter than the default block size, for example because it's - the last block of a file, it's assumed filled with 0 at the end in the XOR operation. + This file is read and written by the "sync" and "fix" commands, and + only read by "check". + + For all the blocks at a given position, the parity information is + computed with the XOR operator applied to all the blocks. + + When a file block is shorter than the default block size, for example + because it's the last block of a file, it's assumed as filled with 0 + at the end. Copyright This file is Copyright (C) 2011 Andrea Mazzoleni diff --git a/snapraid.txt b/snapraid.txt index 34d55a6d..8c2e87ae 100644 --- a/snapraid.txt +++ b/snapraid.txt @@ -153,19 +153,31 @@ SnapRAID provides three simple commands that allow to: sync Updates the redundancy information. All the modified files in the disk array are read, and the redundancy data is - updated. + recomputed. + Files are identified by inode and checked by time and size, + meaning that you can move them on the disk without triggering + any redundancy recomputation. You can stop this process at any time pressing Ctrl+C, without losing the work already done. + The "content" and "parity" files are modified if necessary. + The files in the array are NOT modified. check - Checks all the files the redundancy data. All the files - are hashed and compared with the snapshot saved in the - previous "sync" command. + Checks all the files and the redundancy data. + All the files are hashed and compared with the snapshot saved + in the previous "sync" command. + Files are identified by path, and checked by content. + Nothing is modified. fix Checks and fix all the files. It's like "check" but it also tries to fix problems reverting the state of the disk array at the previous "sync" command. + After a successful "fix", you should also run a "sync" + command to update the new state of the files. + The "content" file is NOT modified. + The "parity" file is modified if necessary. + The files in the array are modified if necessary. 6 OPTIONS @@ -334,10 +346,15 @@ For example: 9 CONTENT ========= -SnapRAID creates a content file describing the content of your disk array. +SnapRAID creates a content file describing the content of your disk +array. -You should never change it manually, although the format of this file is -described here. +It's a text file, listing all the files in your disk array. + +This file is read and written by the "sync" command, and only read by +"fix" and "check". +You should never change it manually, although the format of this file +is described here. blk_size SIZE Defines the size of the block in bytes. It must match the size @@ -361,20 +378,31 @@ described here. HASH is the md5 of the block. In the last block of the file, the HASH is the hash of only the used part of the block. + inv BLOCK [HASH] + Like "blk", but inform that the parity of this block is invalid. + The HASH may be missing if not yet computed. + This field is used only when you interrupt manually the "sync" + command. + 10 PARITY ========= -SnapRAID creates a parity file containing the parity information of your disk array. +SnapRAID creates a parity file containing the redundancy information +of your disk array. -It's a binary file, containing the parity information of all the blocks defined -in the "content" file. +It's a binary file, containing the computed parity of all the blocks +defined in the "content" file. -For all the blocks at a given position, the parity information is computed with -the XOR operator applied to all the blocks. +This file is read and written by the "sync" and "fix" commands, and +only read by "check". -When a file block is shorter than the default block size, for example because it's -the last block of a file, it's assumed filled with 0 at the end in the XOR operation. +For all the blocks at a given position, the parity information is +computed with the XOR operator applied to all the blocks. + +When a file block is shorter than the default block size, for example +because it's the last block of a file, it's assumed as filled with 0 +at the end. 11 COPYRIGHT