snapraid/snapraid.1

.TH "SnapRAID Backup For Disk Arrays" 1
.SH NAME
snapraid \- SnapRAID Backup For Disk Arrays
.SH SYNOPSIS 
snapraid [\-c, \-\-conf CONFIG]
.PD 0
.PP
.PD
	[\-f, \-\-filter PATTERN] [\-d, \-\-filter\-disk NAME]
.PD 0
.PP
.PD
	[\-m, \-\-filter\-missing] [\-e, \-\-filter\-error]
.PD 0
.PP
.PD
	[\-a, \-\-audit\-only] [\-h, \-\-pre\-hash] [\-i, \-\-import DIR]
.PD 0
.PP
.PD
	[\-p, \-\-percentage PERC] [\-o, \-\-older\-than DAYS]
.PD 0
.PP
.PD
	[\-Z, \-\-force\-zero] [\-E, \-\-force\-empty]
.PD 0
.PP
.PD
	[\-U, \-\-force\-uuid] [\-D, \-\-force\-device]
.PD 0
.PP
.PD
	[\-v, \-\-verbose] [\-l, \-\-log FILE]
.PD 0
.PP
.PD
	[\-s, \-\-start BLKSTART] [\-t, \-\-count BLKCOUNT]
.PD 0
.PP
.PD
	status|sync|scrub|fix|check|list|diff|dup|pool|rehash
.PD 0
.PP
.PD
.PP
snapraid [\-V, \-\-version] [\-H, \-\-help] [\-C, \-\-gen\-conf CONTENT]
.PD 0
.PP
.PD
.SH DESCRIPTION 
SnapRAID is a backup program for disk arrays. It stores parity
information of your data and it\(cqs able to recover from up to six
disk failures.
.PP
SnapRAID is mainly targeted for a home media center, with a lot of
big files that rarely change.
.PP
Beside the ability to recover from disk failures, other
features of SnapRAID are:
.PD 0
.IP \(bu
All your data is hashed to ensure data integrity and to avoid
silent corruption.
.IP \(bu
If the failed disks are too many to allow a recovery,
you lose the data only on the failed disks.
All the data in the other disks is safe.
.IP \(bu
If you accidentally delete some files in a disk, you can
recover them.
.IP \(bu
You can start with already filled disks.
.IP \(bu
The disks can have different sizes.
.IP \(bu
You can add disks at any time.
.IP \(bu
It doesn\(cqt lock\-in your data. You can stop using SnapRAID at any
time without the need to reformat or move data.
.PD
.PP
The official site of SnapRAID is:
.PP
.RS 4
http://snapraid.sourceforge.net
.PD 0
.PP
.PD
.RE
.SH LIMITATIONS 
SnapRAID is in between a RAID and a Backup program trying to get the best
benefits of them. Although it also has some limitations that you should
consider before using it.
.PP
The main one is that if a disk fails, and you haven\(cqt recently synced,
you may not able to do a complete recover.
More specifically, you may be unable to recover up to the size of the
amount of the changed or deleted files from the last sync operation.
This happens even if the files changed or deleted are not in the
failed disk.
New added files don\(cqt prevent the recovering of the already existing
files. You may only lose the just added files, if they are on the failed
disk.
.PP
This is the reason because SnapRAID is better suited for data that
rarely change.
.PP
Other limitations are:
.PD 0
.IP \(bu
You have different file\-systems for each disk.
Using a RAID you have only a big file\-system.
.IP \(bu
It doesn\(cqt stripe data.
With RAID you get a speed boost with striping.
.IP \(bu
It doesn\(cqt support real\-time recovery.
With RAID you do not have to stop working when a disk fails.
.IP \(bu
It\(cqs able to recover damages only from a limited number of disks.
With a Backup you are able to recover from a complete
failure of the whole disk array.
.IP \(bu
Only file, timestamps, symlinks and hardlinks are saved.
Permissions, ownership and extended attributes are not saved.
.PD
.SH GETTING STARTED 
To use SnapRAID you need to first select one disk of your disk array
to dedicate at the \(a"parity\(a" information. With one disk for parity you
will be able to recover from a single disk failure, like RAID5.
.PP
If you want to be able to recover from more disk failures, like RAID6,
you must reserve additional disks for parity. Any additional parity
disk allow to recover from one more disk failure.
.PP
As parity disks, you have to pick the biggest disks in the array,
as the parity information may grow in size as the biggest data
disk in the array.
.PP
These disks will be dedicated to store the \(a"parity\(a" files.
You should not store your data in them.
.PP
The list of files is saved in the \(a"content\(a" files, usually
stored in the data, parity or boot disks.
These files contain the details of your backup, with all the
checksums to verify its integrity.
The \(a"content\(a" file is stored in multiple copies, and each one must
be in a different disk, to ensure that in even in case of multiple
disk failures at least one copy is available.
.PP
For example, suppose that you are interested only at one parity level
of protection, and that your disks are present in:
.PP
.RS 4
/mnt/diskp <\- selected disk for parity
.PD 0
.PP
.PD
/mnt/disk1 <\- first disk to backup
.PD 0
.PP
.PD
/mnt/disk2 <\- second disk to backup
.PD 0
.PP
.PD
/mnt/disk3 <\- third disk to backup
.PD 0
.PP
.PD
.RE
.PP
you have to create the configuration file /etc/snapraid.conf with
the following options:
.PP
.RS 4
parity /mnt/diskp/parity
.PD 0
.PP
.PD
content /var/snapraid/content
.PD 0
.PP
.PD
content /mnt/disk1/content
.PD 0
.PP
.PD
content /mnt/disk2/content
.PD 0
.PP
.PD
disk d1 /mnt/disk1/
.PD 0
.PP
.PD
disk d2 /mnt/disk2/
.PD 0
.PP
.PD
disk d3 /mnt/disk3/
.PD 0
.PP
.PD
.RE
.PP
If you are in Windows, you should use drive letters and backslashes
instead of slashes, and if you like, also file extensions.
.PP
.RS 4
parity E:\(rsparity.par
.PD 0
.PP
.PD
content C:\(rssnapraid\(rscontent.lst
.PD 0
.PP
.PD
content F:\(rsarray\(rscontent.lst
.PD 0
.PP
.PD
content G:\(rsarray\(rscontent.lst
.PD 0
.PP
.PD
disk d1 F:\(rsarray\(rs
.PD 0
.PP
.PD
disk d2 G:\(rsarray\(rs
.PD 0
.PP
.PD
disk d3 H:\(rsarray\(rs
.PD 0
.PP
.PD
.RE
.PP
At this point you are ready to start the \(a"sync\(a" command to build the
parity information.
.PP
.RS 4
snapraid sync
.PD 0
.PP
.PD
.RE
.PP
This process may take some hours the first time, depending on the size
of the data already present in the disks. If the disks are empty
the process is immediate.
.PP
You can stop it at any time pressing Ctrl+C, and at the next run it
will start where interrupted.
.PP
When this command completes, your data is SAFE.
.PP
At this point you can start using your array as you like, and periodically
update the parity information running the \(a"sync\(a" command.
.SS Restoring and Undeleting 
In recovering SnapRAID is more like a backup program than a RAID system,
and it can be used to restore or undelete only a single file or directory
to its previous state using the \-f, \-\-filter option :
.PP
.RS 4
snapraid fix \-f FILE
.PD 0
.PP
.PD
.RE
.PP
or for a directory:
.PP
.RS 4
snapraid fix \-f DIR/
.PD 0
.PP
.PD
.RE
.PP
You can also use it to recover only accidentally deleted files inside
a directory using the \-m, \-\-filter\-missing option, that restores
only missing files, leaving untouched all the others.
.PP
.RS 4
snapraid fix \-m \-f DIR/
.PD 0
.PP
.PD
.RE
.PP
Or to recover all the deleted files in all the drives with:
.PP
.RS 4
snapraid fix \-m
.PD 0
.PP
.PD
.RE
.PP
If instead you have lost an entire disk and you want to recover it,
please see the \(cqRecovering\(cq chapter.
.SS Scrubbing 
To periodically check the data and parity for errors, you can
run the \(a"scrub\(a" command.
.PP
.RS 4
snapraid scrub
.PD 0
.PP
.PD
.RE
.PP
This command verifies only the oldest data in your array.
Every run of the command checks about 12% of the array,
but nothing newer than 10 days.
You can use the \-p, \-\-percentage option to specify a different amount,
and the \-o, \-\-older\-than option to specify a different age in days.
For example, to check 5% of the array older than 20 days use:
.PP
.RS 4
snapraid \-p 5 \-o 20 scrub
.PD 0
.PP
.PD
.RE
.PP
If silent errors are found, the corresponding blocks are marked as bad
in the \(a"content\(a" file, and listed in the \(a"status\(a" command.
.PP
.RS 4
snapraid status
.PD 0
.PP
.PD
.RE
.PP
To fix them, you can use the \(a"fix\(a" command filtering for files
containing bad blocks:
.PP
.RS 4
snapraid \-e fix
.PD 0
.PP
.PD
.RE
.PP
At the next \(a"scrub\(a" the errors will disappear from the \(a"status\(a" report
if really fixed. You can use \-p 0 to scrub only blocks marked as bad.
.PP
.RS 4
snapraid \-p 0 scrub
.PD 0
.PP
.PD
.RE
.SS Pooling 
To have all the files in your array shown in the same directory tree,
you can enable \(a"pooling\(a", that consists in creating a virtual view of all
the files in your array using symbolic links.
.PP
You can configure the \(a"pooling\(a" directory in the configuration file with:
.PP
.RS 4
pool /pool
.PD 0
.PP
.PD
.RE
.PP
or, if you are in Windows, with:
.PP
.RS 4
pool C:\(rspool
.PD 0
.PP
.PD
.RE
.PP
and then run the \(a"pool\(a" command to create or update the virtual view.
.PP
.RS 4
snapraid pool
.PD 0
.PP
.PD
.RE
.PP
If you are using a Unix platform and you want to share such directory
in the network to either Windows or Unix machines, you should add
to your /etc/samba/smb.conf the following options:
.PP
.RS 4
# In the global section of smb.conf
.PD 0
.PP
.PD
unix extensions = no
.PD 0
.PP
.PD
.RE
.PP
.RS 4
# In the share section of smb.conf
.PD 0
.PP
.PD
[pool]
.PD 0
.PP
.PD
comment = Pool
.PD 0
.PP
.PD
path = /pool
.PD 0
.PP
.PD
read only = yes
.PD 0
.PP
.PD
guest ok = yes
.PD 0
.PP
.PD
wide links = yes
.PD 0
.PP
.PD
follow symlinks = yes
.PD 0
.PP
.PD
.RE
.PP
In Windows the same sharing operation is not so straightforward,
because Windows shares the symbolic links as they are, and that
requires the network clients to resolve them remotely.
.PP
To make it working, besides sharing in the network the pool directory,
you must also share all the disks independently, using as share points
the disk names as defined in the config file. You must also specify in
the \(a"share\(a" option of the configure file, the Windows UNC path that remote
clients needs to use to access such shared disks.
.PP
For example, operating from a server named \(a"darkstar\(a", you can use
the options:
.PP
.RS 4
disk d1 F:\(rsarray\(rs
.PD 0
.PP
.PD
disk d2 G:\(rsarray\(rs
.PD 0
.PP
.PD
disk d3 H:\(rsarray\(rs
.PD 0
.PP
.PD
pool C:\(rspool
.PD 0
.PP
.PD
share \(rs\(rsdarkstar
.PD 0
.PP
.PD
.RE
.PP
and share the following dirs in the network:
.PP
.RS 4
\(rs\(rsdarkstar\(rspool \-> C:\(rspool
.PD 0
.PP
.PD
\(rs\(rsdarkstar\(rsd1 \-> F:\(rsarray
.PD 0
.PP
.PD
\(rs\(rsdarkstar\(rsd2 \-> G:\(rsarray
.PD 0
.PP
.PD
\(rs\(rsdarkstar\(rsd3 \-> H:\(rsarray
.PD 0
.PP
.PD
.RE
.PP
to allow remote clients to access all the files at \(rs\(rsdarkstar\(rs\(rspool.
.PP
You may also need to configure remote clients, to enable the access at
remote symlinks with the command:
.PP
.RS 4
fsutil behavior set SymlinkEvaluation L2L:1 R2R:1 L2R:1 R2L:1
.PD 0
.PP
.PD
.RE
.SH COMMANDS 
SnapRAID provides a few simple commands that allow to:
.PD 0
.IP \(bu
Prints a report of the status of the array \-> \(a"status\(a"
.IP \(bu
Makes a backup/snapshot \-> \(a"sync\(a"
.IP \(bu
Periodically checks data \-> \(a"scrub\(a"
.IP \(bu
Restore the last backup/snapshot \-> \(a"fix\(a".
.PD
.PP
Take care that the commands have to be written in lower case.
.SS status 
Prints a summary of the state of the disk array.
.PP
It includes information about the parity fragmentation, how old
are the blocks without checking, and all the recorded silent
errors encountered while scrubbing.
.PP
Nothing is modified.
.SS sync 
Updates the parity information. All the modified files
in the disk array are read, and the parity data is
recomputed.
.PP
Files are identified by path and/or inode and checked by
size and timestamp.
If the size or timestamp are different, the parity data is
recomputed for the whole file.
With inode you can move them on the disk without triggering
any parity recomputation.
.PP
You can stop this process at any time pressing Ctrl+C,
without losing the work already done.
At the next run the \(a"sync\(a" process will start where
interrupted.
.PP
The \(a"content\(a" and \(a"parity\(a" files are modified if necessary.
The files in the array are NOT modified.
.SS scrub 
Scrubs the array, checking for silent errors in data or parity disks.
.PP
For each command invocation, the 12% of the array is checked, but
nothing that it\(cqs more recent than 10 days.
This means that scrubbing once a week, every bit of data is checked
at least one time every two months.
.PP
You can use the \-p, \-\-percentage option to specify a different amount,
and the \-o, \-\-older\-than option to specify a different age in days.
You can have a full scrub with \(a"\-p100 \-o0\(a".
.PP
Any silent error identified is recorded in the content file,
and it\(cqs listed in the \(a"status\(a" command until it\(cqs fixed calling
\(a"fix\(a" and then \(a"scrub\(a".
.PP
The oldest blocks are scrubbed first ensuring an optimal check.
Blocks already marked as bad are always checked, and if found
correct, they are automatically unmarked.
.PP
It\(cqs recommended to run \(a"scrub\(a" on a synched array, to avoid to have
reported error caused by unsynced data. These errors are recognized
as not being silent errors, and the blocks are not marked as bad,
but such errors are reported in the output of the command.
.PP
Files are identified only by path, and not by inode.
.PP
The \(a"content\(a" file is modified to update the time of the last check
of each block, and to mark bad blocks.
The \(a"parity\(a" files are NOT modified.
The files in the array are NOT modified.
.SS fix 
Fix all the files and the parity data.
.PP
All the files and the parity data are compared with the snapshot
state saved in the last \(a"sync\(a" command.
If a difference is found, it\(cqs reverted at the stored snapshot.
.PP
Note that \(a"fix\(a" doesn\(cqt differentiate from errors or intentional
changes at files. It just reverts the state at the last \(a"sync\(a" command.
.PP
By default the full array is processed. Use the filter options
to select a subset of files or disks to operate on.
To only fix errors found with \(a"scrub\(a" and reported in \(a"status\(a",
you can use the \-e, \-\-filter\-error option.
.PP
All the files that cannot be fixed are renamed adding
the \(a".unrecoverable\(a" extension.
.PP
Files are identified only by path, and not by inode.
.PP
The \(a"content\(a" file is NOT modified.
The \(a"parity\(a" files are modified if necessary.
The files in the array are modified if necessary.
.SS check 
Verify all the files and the parity data.
.PP
It works just like \(a"fix\(a", but it only simulates a recovery
and no change is written in the array.
.PP
This command is mostly intended for manual verifications,
like after a recovery process or in other special conditions.
For periodic and scheduled checks uses the \(a"scrub\(a" command.
.PP
If you use the \-a, \-\-audit\-only option, only the file
data is checked, and the parity data is ignored for a
faster run.
.PP
Files are identified only by path, and not by inode.
.PP
Nothing is modified.
.SS list 
Lists all the files contained in the array at the time of the
last \(a"sync\(a" command.
.PP
Nothing is modified.
.SS diff 
Lists all the files modified from the last \(a"sync\(a" command that
need to have their parity data recomputed.
.PP
This command doesn\(cqt check the file data, but only the file timestamp
size and inode.
.PP
Nothing is modified.
.SS dup 
Lists all the duplicate files. Two files are assumed equal if their
hashes are matching. The file data is not read, but only the
precomputed hashes are used.
.PP
Nothing is modified.
.SS pool 
Creates or updates in the \(a"pooling\(a" directory a virtual view of all
the files of your disk array.
.PP
The files are not really copied here, but just linked using
symbolic links.
.PP
When updating, all the present symbolic links and empty
subdirectories are deleted and replaced with the new
view of the array. Any other regular file is left in place.
.PP
Nothing is modified outside the pool directory.
.SS rehash 
Schedules a rehash of the whole array.
.PP
This option can be used to change the hash kind used,
typically when upgrading from a 32 bits system to a 64
bits one to switch from MurmurHash3 to the faster SpookyHash.
.PP
If you are already using the optimal hash, this command
do nothing and tells you that nothing has to be done.
.PP
The rehash isn\(cqt done immediately, but it takes place
progressively during the \(a"sync\(a" and \(a"scrub\(a" commands.
.PP
You can get the rehash state using the \(a"status\(a" command.
.PP
During the rehash, SnapRAID maintains full functionality,
with the only exception of the \(a"dup\(a" command not able to detect
duplicated files using a different hash.
.SH OPTIONS 
SnapRAID provides the following options:
.TP
.B \-c, \-\-conf CONFIG
Selects the configuration file. If not specified it\(cqs assumed
the file \(a"/etc/snapraid.conf\(a" in Unix, and \(a"snapraid.conf\(a" in
the current directory in Windows.
.TP
.B \-f, \-\-filter PATTERN
Filters the files to process in the \(a"check\(a" and \(a"fix\(a"
commands.
Only the files matching the entered pattern are processed.
This option can be used many times.
See the PATTERN section for more details in the
pattern specifications.
In Unix, ensure to quote globbing chars if used.
This option can be used only with the \(a"check\(a" and \(a"fix\(a" commands.
Note that it cannot be used with \(a"sync\(a" and \(a"scrub\(a", because they always
process the whole array.
.TP
.B \-d, \-\-filter\-disk NAME
Filters the files to process in the \(a"check\(a" and \(a"fix\(a"
commands.
Only the files present in the specified disk are processed.
You must specify a disk name as named in the configuration
file.
In \(a"check\(a", you can make it faster, specifying also \-a, \-\-audit\-only
option, to avoid to access other disks to check parity data.
If you combine more \-\-filter, \-\-filter\-disk and \-\-filter\-missing options,
only files matching all the set of filters are selected.
This option can be used many times.
This option can be used only with the \(a"check\(a" and \(a"fix\(a" commands.
Note that it cannot be used with \(a"sync\(a" and \(a"scrub\(a", because they always
process the whole array.
.TP
.B \-m, \-\-filter\-missing
Filters the files to process in the \(a"check\(a" and \(a"fix\(a"
commands.
Only the files missing/deleted from the array are processed.
When used with \(a"fix\(a", this is a kind of \(a"undelete\(a" command.
If you combine more \-\-filter, \-\-filter\-disk and \-\-filter\-missing options,
only files matching all the set of filters are selected.
This option can be used only with the \(a"check\(a" and \(a"fix\(a" commands.
Note that it cannot be used with \(a"sync\(a" and \(a"scrub\(a", because they always
process the whole array.
.TP
.B \-e, \-\-filter\-error
Filters the files to process in the \(a"check\(a" and \(a"fix\(a"
commands.
It processes only the files containing blocks marked with silent
errors during the \(a"sync\(a" and \(a"scrub\(a" command, and listed in the
\(a"status\(a" command.
This option can be used only with the \(a"check\(a" and \(a"fix\(a" commands.
.TP
.B \-p, \-\-percentage PERC
Selects the part of the array to process in the \(a"scrub\(a" command.
PERC is a numeric value from 0 to 100, default is 12.
When specifying 0, only the blocks marked as bad are scrubbed.
This option can be used only with the \(a"scrub\(a" command.
.TP
.B \-o, \-\-older\-than DAYS
Selects the older the part of the array to process in the
\(a"scrub\(a" command.
DAYS is the minimum age in days for a block to be scrubbed,
default is 10.
Blocks marked as bad are always scrubbed despite this option.
This option can be used only with the \(a"scrub\(a" command.
.TP
.B \-a, \-\-audit\-only
In the \(a"check\(a" command verifies the hash of the files without
doing any kind of check on the parity data.
If you are interested in checking only the file data this
option can speedup a lot the checking process.
This option can be used only with the \(a"check\(a" command.
.TP
.B \-h, \-\-pre\-hash
In the \(a"sync\(a" command run a preliminary hashing phase of all
the new data to ensure that during the parity computation
the data read is correct.
Normally in \(a"sync\(a" no preliminary hashing is done, and the new
data is hashed directly during the parity computation when it\(cqs
read for the first time,
This happens when the system is under heavy pressure due all
disks spinning and CPU busy, and in such extreme conditions,
if your machine has a latent hardware problem, it\(cqs possible to
encouter silent errors what cannot be detected because the data
is not yet hashed.
To avoid this risk, you can enable the \(a"pre\-hash\(a" mode and have
all the data hashed two times to ensure its integrity.
This option can be used only with the \(a"sync\(a" command.
.TP
.B \-i, \-\-import DIR
Imports from the specified directory any file that you deleted
from the array after the last \(a"sync\(a" command.
If you still have such files, they could be used by the \(a"check\(a"
and \(a"fix\(a" commands to improve the recover process.
The files are read also in subdirectories and they are
identified regardless of their name.
This option can be used only with the \(a"check\(a" and \(a"fix\(a" commands.
.TP
.B \-Z, \-\-force\-zero
Forces the insecure operation of syncing a file with zero
size that before was not.
If SnapRAID detects a such condition, it stops proceeding
unless you specify this option.
This allows to easily detect when after a system crash,
some accessed files were zeroed.
This is a possible condition in Linux with the ext3/ext4
filesystems.
This option can be used only with the \(a"sync\(a" command.
.TP
.B \-E, \-\-force\-empty
Forces the insecure operation of syncing a disk with all
the original files missing.
If SnapRAID detects that all the files originally present
in the disk are missing or rewritten, it stops proceeding
unless you specify this option.
This allows to easily detect when a data file\-system is not
mounted.
This option can be used only with the \(a"sync\(a" command.
.TP
.B \-U, \-\-force\-uuid
Forces the insecure operation of syncing, checking and fixing
with disks that have changed their UUID.
If SnapRAID detects that some disks have changed UUID,
it stops proceeding unless you specify this option.
This allows to detect when your disks are mounted in the
wrong mount points.
It\(cqs anyway allowed to have a single UUID change with
single parity, and more with multiple parity, because it\(cqs
the normal case of replacing disks after a recovery.
This option can be used only with the \(a"sync\(a", \(a"check\(a" or
\(a"fix\(a" command.
.TP
.B \-D, \-\-force\-device
Forces the insecure operation of fixing with disks on the same
physical device.
If SnapRAID detects that some disks have the same device ID,
it stops proceeding, because it\(cqs not a supported configuration.
But it could happen that you want to temporarily restore a lost
disk in the free space left in an already used disk. and this
option allows you to continue anyway.
.TP
.B \-l, \-\-log FILE
Write a detailed log of errors found in check and fix.
This log contains the exact specification of which block of
any file is not recoverable and why.
If this option is not specified, no detailed log is printed,
and you\(cqll get only a summary at the end of the operations.
When checking and fixing this allows to keep separated
the possible huge list of errors from the human readable
output.
If the specified path starts with \(cq>>\(cq the file is opened
in append mode. Occurrences of %D and %T in the name are
replaced with the date and time in the format YYYYMMDD and
HHMMSS.
.TP
.B \-s, \-\-start BLKSTART
Starts the processing from the specified
block number. It could be useful to retry to check
or fix some specific block, in case of a damaged disk.
It\(cqs present mainly for advanced manual recovering.
.TP
.B \-t, \-\-count BLKCOUNT
Processes only the specified number of blocks.
It\(cqs present mainly for advanced manual recovering.
.TP
.B \-C, \-\-gen\-conf CONTENT_FILE
Generates a dummy configuration file from an existing
content file.
The configuration file is written in the standard output,
and it doesn\(cqt overwrite an existing one.
This configuration file also contains the information
needed to reconstruct the disk mount points, in case you
lose the entire system.
.TP
.B \-v, \-\-verbose
Prints more information in the processing.
.TP
.B \-h, \-\-help
Prints a short help screen.
.TP
.B \-V, \-\-version
Prints the program version.
.SH CONFIGURATION 
SnapRAID requires a configuration file to know where your disk array
is located, and where storing the parity information.
.PP
This configuration file is located in /etc/snapraid.conf in Unix or
in the execution directory in Windows.
.PP
It should contain the following options (case sensitive):
.SS parity FILE 
Defines the file to use to store the parity information.
The parity enables the protection from a single disk
failure, like RAID5.
.PP
It must be placed in a disk dedicated for this purpose with
as much free space as the biggest disk in the array.
Leaving the parity disk reserved for only this file ensures that
it doesn\(cqt get fragmented, improving the performance.
.PP
This option is mandatory and it can be used only one time.
.SS [2,3,4,5,6]\-parity FILE 
Defines the files to use to store extra parity information.
For each parity file specified, one additional level of protection
is enabled:
.PD 0
.IP \(bu
2\-parity enables RAID6 double parity.
.IP \(bu
3\-parity enables triple parity
.IP \(bu
4\-parity enables quad parity
.IP \(bu
5\-parity enables penta (five) parity
.IP \(bu
6\-parity enables hexa (six) parity
.PD
.PP
Each parity level requires also all the files of the previous levels.
.PP
Each file must be placed in a disk dedicated for this purpose with
as much free space as the biggest disk in the array.
Leaving the parity disks reserved for only these files ensures that
they doesn\(cqt get fragmented, improving the performance.
.PP
These options are optional and they can be used only one time.
.SS z\-parity FILE 
Defines an alternate file and format to store the triple parity.
.PP
This option is an alternative at \(cq3\-parity\(cq mainly intended for
low\-end CPUs like ARM or AMD Phenom, Athlon and Opteron that don\(cqt
support the SSSE3 instructions set, and in such case it may provide
a better performance.
.PP
This format is similar at the one used by the Linux Kernel RAID6 and
ZFS RAIDZ3, but it doesn\(cqt work beyond triple parity.
.PP
When using \(cq3\-parity\(cq you will be warned if it\(cqs recommended to use
the \(cqz\-parity\(cq format for a performance improvement.
.PP
It\(cqs possible to convert from one format to another, adjusting
the configuration file with the wanted z\-parity or 3\-parity file,
and using \(cqfix\(cq to recreate it.
.SS content FILE 
Defines the file to use to store the list and checksums of all the
files present in your disk array.
.PP
It can be placed in the disk used to store data, parity, or
any other disk available.
If you use a data disk, this file is automatically excluded
from the \(a"sync\(a" process.
.PP
This option is mandatory and it can be used more times to save
more copies of the same files.
.PP
You have to store at least one copy for each parity disk used
plus one. Using some more doesn\(cqt hurt.
.SS disk NAME DIR 
Defines the name and the mount point of the disks of the array.
NAME is used to identify the disk, and it must be unique.
DIR is the mount point of the disk in the filesystem.
.PP
You can change the mount point as you like, as long you
keep the NAME fixed.
.PP
You should use one option for each disk of the array.
.SS nohidden 
Excludes all the hidden files and directory.
In Unix hidden files are the ones starting with \(a".\(a".
In Windows they are the ones with the hidden attribute.
.SS exclude/include PATTERN 
Defines the file or directory patterns to exclude and include
in the sync process.
All the patterns are processed in the specified order.
.PP
If the first pattern that matches is an \(a"exclude\(a" one, the file
is excluded. If it\(cqs an \(a"include\(a" one, the file is included.
If no pattern matches, the file is excluded if the last pattern
specified is an \(a"include\(a", or included if the last pattern
specified is an \(a"exclude\(a".
.PP
See the PATTERN section for more details in the pattern
specifications.
.PP
This option can be used many times.
.SS blocksize SIZE_IN_KIBIBYTES 
Defines the basic block size in kibi bytes of the parity
blocks. Where one kibi bytes is 1024 bytes.
The default is 256 and it should work for most conditions.
You could increase this value if you do not have enough RAM
memory to run SnapRAID.
.PP
As a rule of thumb, with 4 GiB or more memory use the default 256,
with 2 GiB use 512, and with 1 GiB use 1024.
.PP
In more details SnapRAID requires about TS*28/BS bytes
of RAM memory to run. Where TS is the total size in bytes of
your disk array, and BS is the block size in bytes.
.PP
For example with 4 disk of 3 TiB and a block size of 256 KiB
(1 KiB = 1024 Bytes) you have:
.PP
RAM = (4 * 3 * 2^40) * 28 / (256 * 2^10) = 1.4 GiB
.PD 0
.PP
.PD
.PP
You could instead decrease this value if you have a lot of
small files in the disk array. For each file, even if of few
bytes, a whole block is always allocated, so you may have a lot
of unused space.
As approximation, you can assume that half of the block size is
wasted for each file.
.PP
For example, with 10000 files and a 256 KiB block size, you are
going to waste 1.2 GiB.
.SS autosave SIZE_IN_GIBIBYTES 
Automatically save the state when synching after the specified amount
of GiB processed.
This option is useful to avoid to restart from scratch long \(a"sync\(a"
commands interrupted by a machine crash, or any other event that
may interrupt SnapRAID.
The SIZE argument is specified in gibibytes. Where one gibi bytes
is 1073741824 bytes.
.SS pool DIR 
Defines the pooling directory where the virtual view of the disk
array is created using the \(a"pool\(a" command.
.PP
The directory must already exist.
.SS share UNC_DIR 
Defines the Windows UNC path required to access the disks remotely.
.PP
If this option is specified, the symbolic links created in the pool
directory use this UNC path to access the disks.
Without this option the symbolic links generated use only local paths,
not allowing to share the pool directory in the network.
.PP
The symbolic links are formed using the specified UNC path, adding the
disk name as specified in the \(a"disk\(a" option, and finally adding the
file dir and name.
.PP
This option is only required for Windows.
.SS Examples 
An example of a typical configuration for Unix is:
.PP
.RS 4
parity /mnt/diskp/parity
.PD 0
.PP
.PD
content /mnt/diskp/content
.PD 0
.PP
.PD
content /var/snapraid/content
.PD 0
.PP
.PD
disk d1 /mnt/disk1/
.PD 0
.PP
.PD
disk d2 /mnt/disk2/
.PD 0
.PP
.PD
disk d3 /mnt/disk3/
.PD 0
.PP
.PD
exclude /lost+found/
.PD 0
.PP
.PD
exclude /tmp/
.PD 0
.PP
.PD
.RE
.PP
An example of a typical configuration for Windows is:
.PP
.RS 4
parity E:\(rsparity.par
.PD 0
.PP
.PD
content E:\(rscontent.lst
.PD 0
.PP
.PD
content C:\(rssnapraid\(rscontent.lst
.PD 0
.PP
.PD
disk d1 G:\(rsarray\(rs
.PD 0
.PP
.PD
disk d2 H:\(rsarray\(rs
.PD 0
.PP
.PD
disk d3 I:\(rsarray\(rs
.PD 0
.PP
.PD
exclude Thumbs.db
.PD 0
.PP
.PD
exclude \(rs$RECYCLE.BIN
.PD 0
.PP
.PD
exclude \(rsSystem Volume Information
.PD 0
.PP
.PD
.RE
.SH PATTERN 
Patterns are used to select a subset of files to exclude or include in
the process.
.PP
There are four different types of patterns:
.TP
.B FILE
Selects any file named as FILE. You can use any globbing
character like * and ?.
This pattern is applied only to files and not to directories.
.TP
.B DIR/
Selects any directory named DIR and everything inside.
You can use any globbing character like * and ?.
This pattern is applied only to directories and not to files.
.TP
.B /PATH/FILE
Selects the exact specified file path. You can use any
globbing character like * and ? but they never match a
directory slash.
This pattern is applied only to files and not to directories.
.TP
.B /PATH/DIR/
Selects the exact specified directory path and everything
inside. You can use any globbing character like * and ? but
they never match a directory slash.
This pattern is applied only to directories and not to files.
.PP
Note that when you specify an absolute path starting with /, it\(cqs
applied at the array root dir and not at the local filesystem root dir.
.PP
In Windows you can use the backslash \(rs instead of the forward slash /.
Note that Windows system directories, junctions, mount points, and any
other Windows special directory are treated just as files, meaning that
to exclude them you must use a file rule, and not a directory one.
.PP
In the configuration file, you can use different strategies to filter
the files to process.
The simplest one is to use only \(a"exclude\(a" rules to remove all the
files and directories you do not want to process. For example:
.PP
.RS 4
# Excludes any file named \(a"*.unrecoverable\(a"
.PD 0
.PP
.PD
exclude *.unrecoverable
.PD 0
.PP
.PD
# Excludes the root directory \(a"/lost+found\(a"
.PD 0
.PP
.PD
exclude /lost+found/
.PD 0
.PP
.PD
# Excludes any sub\-directory named \(a"tmp\(a"
.PD 0
.PP
.PD
exclude tmp/
.PD 0
.PP
.PD
.RE
.PP
The opposite way is to define only the file you want to process, using
only \(a"include\(a" rules. For example:
.PP
.RS 4
# Includes only some directories
.PD 0
.PP
.PD
include /movies/
.PD 0
.PP
.PD
include /musics/
.PD 0
.PP
.PD
include /pictures/
.PD 0
.PP
.PD
.RE
.PP
The final way, is to mix \(a"exclude\(a" and \(a"include\(a" rules. In this case take
care that the order of rules is important. Previous rules have the
precedence over the later ones.
To get things simpler you can first have all the \(a"exclude\(a" rules and then
all the \(a"include\(a" ones. For example:
.PP
.RS 4
# Excludes any file named \(a"*.unrecoverable\(a"
.PD 0
.PP
.PD
exclude *.unrecoverable
.PD 0
.PP
.PD
# Excludes any sub\-directory named \(a"tmp\(a"
.PD 0
.PP
.PD
exclude tmp/
.PD 0
.PP
.PD
# Includes only some directories
.PD 0
.PP
.PD
include /movies/
.PD 0
.PP
.PD
include /musics/
.PD 0
.PP
.PD
include /pictures/
.PD 0
.PP
.PD
.RE
.PP
On the command line, using the \-f option, you can only use \(a"include\(a"
patterns. For example:
.PP
.RS 4
# Checks only the .mp3 files.
.PD 0
.PP
.PD
# Note the \(a"\(a" use to avoid globbing expansion by the shell in Unix.
.PD 0
.PP
.PD
snapraid \-f \(a"*.mp3\(a" check
.PD 0
.PP
.PD
.RE
.PP
In Unix, when using globbing chars in the command line, you have to
quote them. Otherwise the shell will try to expand them.
.SH RECOVERING 
The worst happened, and you lost a disk!
.PP
DO NOT PANIC! You will be able to recover it!
.PP
The first thing you have to do is to avoid further changes at you disk array.
Disable any remote connection to it, any scheduled process, including any
scheduled SnapRAID nightly sync.
.PP
Then proceed with the following steps.
.SS STEP 1 \-> Reconfigure 
You need some space to recover, even better if you already have an additional
disk, but in case, also an external USB or remote one is enough.
.PP
Change the SnapRAID configuration file and make the \(a"disk\(a" option
of the failed disk to point to a place where you have enough empty space
to recover the files.
.PP
For example, if you have that disk \(a"d1\(a" failed, you can change:
.PP
.RS 4
disk d1 /mnt/disk1/
.PD 0
.PP
.PD
.RE
.PP
to:
.PP
.RS 4
disk d1 /mnt/new_spare_disk/
.PD 0
.PP
.PD
.RE
.SS STEP 2 \-> Fix 
Run the fix command, storing the log in an external file with:
.PP
.RS 4
snapraid \-d NAME \-l fix.log fix
.PD 0
.PP
.PD
.RE
.PP
Where NAME is the name of the disk, like \(a"d1\(a" as in our previous example.
.PP
This command will take a long time.
.PP
Take care that you need also few gigabytes free to store the fix.log file.
Run it from a disk with some free space.
.PP
Now you have recovered all the recoverable. If some file is partially or totally
unrecoverable, it will be renamed adding the \(a".unrecoverable\(a" extension.
.PP
You can get a detailed list of all the unrecoverable blocks in the fix.log file
checking all the lines starting with \(a"unrecoverable:\(a"
.PP
If you are not satisfied of the recovering, you can retry it as many time you wish.
For example, if you have moved away some files from other disks after the last \(a"sync\(a",
you can retry to put them inplace, and retry the \(a"fix\(a".
.PP
If you are satisfied of the recovering, you can now proceed further,
but take care that after synching you will no more able to retry the
\(a"fix\(a" command!
.SS STEP 3 \-> Check 
As paranoid check, you can now run a \(a"check\(a" command to ensure that everything
is OK on the disk.
.PP
.RS 4
snapraid \-d NAME \-a check
.PD 0
.PP
.PD
.RE
.PP
Where NAME is the name of the disk, like \(a"d1\(a" as in our previous example.
.PP
The options \-d and \-a tell SnapRAID to check only the specified disk,
and ignore all the parity data.
.PP
This command will take a long time.
.SS STEP 4 \-> Sync 
Run the \(a"sync\(a" command to resynchronize the array with the new disk.
.PP
.RS 4
snapraid sync
.PD 0
.PP
.PD
.RE
.PP
If everything is recovered, this command is immediate.
.SH CONTENT 
SnapRAID stores the list and checksums of your files in the content file.
.PP
It\(cqs a binary file, listing all the files present in your disk array,
with all the checksums to verify their integrity.
.PP
You do not need to understand its format to use SnapRAID.
.PP
This file is read and written by the \(a"sync\(a" and \(a"scrub\(a" commands, and
only read by \(a"fix\(a", \(a"check\(a" and \(a"status\(a".
.SH PARITY 
SnapRAID stores the parity information of your array in the parity
files.
.PP
They are binary files, containing the computed parity of all the
blocks defined in the \(a"content\(a" file.
.PP
These files are read and written by the \(a"sync\(a" and \(a"fix\(a" commands, and
only read by \(a"scrub\(a" and \(a"check\(a".
.SH ENCODING 
SnapRAID in Unix ignores any encoding. It reads and stores the
file names with the same encoding used by the filesystem.
.PP
In Windows all the names read from the filesystem are converted and
processed in the UTF\-8 format.
.PP
To have the file names printed correctly you have to set the Windows
console in the UTF\-8 mode, with the command \(a"chcp 65001\(a", and use
a TrueType font like \(a"Lucida Console\(a" as console font.
Note that it has effect only on the printed file names, if you
redirect the console output to a file, the resulting file is always
in the UTF\-8 format.
.SH COPYRIGHT 
This file is Copyright (C) 2011 Andrea Mazzoleni
.SH SEE ALSO 
rsync(1)