diff options
Diffstat (limited to 'doc/lziprecover.info')
| -rw-r--r-- | doc/lziprecover.info | 230 |
1 files changed, 161 insertions, 69 deletions
diff --git a/doc/lziprecover.info b/doc/lziprecover.info index 0d39838..a15f890 100644 --- a/doc/lziprecover.info +++ b/doc/lziprecover.info @@ -3,7 +3,7 @@ lziprecover.texinfo. INFO-DIR-SECTION Data Compression START-INFO-DIR-ENTRY -* Lziprecover: (lziprecover). Data recovery tool for lzipped files +* Lziprecover: (lziprecover). Data recovery tool for lzip files END-INFO-DIR-ENTRY @@ -12,18 +12,19 @@ File: lziprecover.info, Node: Top, Next: Introduction, Up: (dir) Lziprecover Manual ****************** -This manual is for Lziprecover (version 1.15-pre1, 17 June 2013). +This manual is for Lziprecover (version 1.15-rc1, 29 July 2013). * Menu: * Introduction:: Purpose and features of lziprecover -* Invoking Lziprecover:: Command line interface -* Repairing Files:: Fixing bit-flip and similar errors -* Merging Files:: Fixing several damaged copies -* File Format:: Detailed format of the compressed file +* Invoking lziprecover:: Command line interface +* Repairing files:: Fixing bit-flip and similar errors +* Merging files:: Fixing several damaged copies +* File format:: Detailed format of the compressed file * Examples:: A small tutorial with examples +* Unzcrash:: Testing the robustness of decompressors * Problems:: Reporting bugs -* Concept Index:: Index of concepts +* Concept index:: Index of concepts Copyright (C) 2009, 2010, 2011, 2012, 2013 Antonio Diaz Diaz. @@ -32,22 +33,38 @@ This manual is for Lziprecover (version 1.15-pre1, 17 June 2013). copy, distribute and modify it. -File: lziprecover.info, Node: Introduction, Next: Invoking Lziprecover, Prev: Top, Up: Top +File: lziprecover.info, Node: Introduction, Next: Invoking lziprecover, Prev: Top, Up: Top 1 Introduction ************** Lziprecover is a data recovery tool and decompressor for files in the -lzip compressed data format (.lz) able to repair slightly damaged files, -recover badly damaged files from two or more copies, extract data from -damaged files, decompress files and test integrity of files. +lzip compressed data format (.lz), able to repair slightly damaged +files, recover badly damaged files from two or more copies, extract data +from damaged files, decompress files and test integrity of files. + + The lzip file format is designed for long-term data archiving. It is +clean, provides very safe 4 factor integrity checking, and is backed by +the recovery capabilities of lziprecover. Lziprecover is able to recover or decompress files produced by any of the compressors in the lzip family; lzip, plzip, minilzip/lzlib, clzip -and pdlzip. It makes lzip files resistant to bit-flip, one of the most -common forms of data corruption, and its recovery capabilities -contribute to make of the lzip format one of the best options for -long-term data archiving. +and pdlzip. + + Lziprecover makes lzip files resistant to bit-flip (one of the most +common forms of data corruption), and can safely merge multiple damaged +backup copies. + + If the cause of file corruption is damaged media, the combination +GNU ddrescue + lziprecover is the best option for recovering data from +multiple damaged copies. *Note ddrescue-example::, for an example. + + If a file is too damaged for lziprecover to repair it, all the +recoverable data in all members of the file can be extracted with the +following command (the resulting file may contain errors and some +garbage data may be produced at the end of each member): + + lziprecover -D0 -i -o file -q file.lz Lziprecover is able to efficiently extract a range of bytes from a multi-member file, because it only decompresses the members containing @@ -64,24 +81,13 @@ damaged files themselves are never modified. When decompressing or testing file integrity, lziprecover behaves like lzip or lunzip. - If a file is too damaged for lziprecover to repair it, all the -recoverable data in all members of the file can be extracted with the -following command (the resulting file may contain errors and some -garbage data may be produced at the end of each member): - - lziprecover -D0 -i -o file -q file.lz - - If the cause of file corruption is damaged media, the combination -GNU ddrescue + lziprecover is the best option for recovering data from -multiple damaged copies. *Note ddrescue-example::, for an example. - Lziprecover is not a replacement for regular backups, but a last line of defense for the case where the backups are also damaged. -File: lziprecover.info, Node: Invoking Lziprecover, Next: Repairing Files, Prev: Introduction, Up: Top +File: lziprecover.info, Node: Invoking lziprecover, Next: Repairing files, Prev: Introduction, Up: Top -2 Invoking Lziprecover +2 Invoking lziprecover ********************** The format for running lziprecover is: @@ -149,8 +155,8 @@ The format for running lziprecover is: Try to produce a correct file merging the good parts of two or more damaged copies. If successful, a repaired copy is written to the file `FILE_fixed.lz'. The exit status is 0 if a correct file could - be produced, 2 otherwise. See the chapter Merging Files (*note - Merging Files::) for a complete description of the merge mode. + be produced, 2 otherwise. See the chapter `Merging files' (*note + Merging files::) for a complete description of the merge mode. `-o FILE' `--output=FILE' @@ -167,10 +173,10 @@ The format for running lziprecover is: `-R' `--repair' Try to repair a file with small errors (up to one byte error per - member). If successful, a repaired copy is written to the file + member). If successful, a repaired copy is written to the file `FILE_fixed.lz'. `FILE' is not modified at all. The exit status - is 0 if the file could be repaired, 2 otherwise. See the chapter - Repairing Files (*note Repairing Files::) for a complete + is 0 if the file could be repaired, 2 otherwise. See the chapter + `Repairing files' (*note Repairing files::) for a complete description of the repair mode. `-s' @@ -199,12 +205,11 @@ The format for running lziprecover is: `--verbose' Verbose mode. When decompressing or testing, further -v's (up to 4) increase the - verbosity level, showing status, dictionary size, compression - ratio, trailer contents (CRC, data size, member size), and up to 6 + verbosity level, showing status, compression ratio, dictionary + size, trailer contents (CRC, data size, member size), and up to 6 bytes of trailing garbage (if any). - Numbers given as arguments to options may be followed by a multiplier and an optional `B' for "byte". @@ -227,9 +232,9 @@ invalid input file, 3 for an internal consistency error (eg, bug) which caused lziprecover to panic. -File: lziprecover.info, Node: Repairing Files, Next: Merging Files, Prev: Invoking Lziprecover, Up: Top +File: lziprecover.info, Node: Repairing files, Next: Merging files, Prev: Invoking lziprecover, Up: Top -3 Repairing Files +3 Repairing files ***************** Lziprecover is able to repair files with small errors (up to one byte @@ -244,13 +249,13 @@ vice versa. It may be caused by bad RAM or even by natural radiation. I have seen a case of bit-flip in a file stored in an USB flash drive. -File: lziprecover.info, Node: Merging Files, Next: File Format, Prev: Repairing Files, Up: Top +File: lziprecover.info, Node: Merging files, Next: File format, Prev: Repairing files, Up: Top -4 Merging Files +4 Merging files *************** If you have several copies of a file but all of them are too damaged to -repair them (*note Repairing Files::), lziprecover can try to produce a +repair them (*note Repairing files::), lziprecover can try to produce a correct file merging the good parts of the damaged copies. The merge may succeed even if some copies of the file have all the @@ -262,17 +267,31 @@ the file. is damaged in all copies), or are adjacent and the boundary can't be determined, or if the copies have too many damaged areas. - To give you an idea of its possibilities, when merging two copies + All the copies must have the same size. If some of them have been +truncated and are therefore smaller than they should, you can extend +them to the correct size with the following command before merging them +with the other copies: + + ddrescue --extend-outfile=<correct_size> small_file.lz extended_file.lz + + If some of the copies have got garbage data at the end and are +therefore larger than they should, you can reduce their sizes to the +correct value with the following command before merging them with the +other copies: + + ddrescue --size=<correct_size> large_file.lz reduced_file.lz + + To give you an idea of its possibilities, when merging two copies, each of them with one damaged area affecting 1 percent of the copy, the probability of obtaining a correct file is about 98 percent. With three -such copies the probability rises to 99.97 percent. For large files with -small errors, the probability approaches 100 percent even with only two -copies. +such copies the probability rises to 99.97 percent. For large files (a +few MB) with small errors (one sector damaged per copy), the probability +approaches 100 percent even with only two copies. -File: lziprecover.info, Node: File Format, Next: Examples, Prev: Merging Files, Up: Top +File: lziprecover.info, Node: File format, Next: Examples, Prev: Merging files, Up: Top -5 File Format +5 File format ************* Perfection is reached, not when there is no longer anything to add, but @@ -343,7 +362,7 @@ additional information before, between, or after them. -File: lziprecover.info, Node: Examples, Next: Problems, Prev: File Format, Up: Top +File: lziprecover.info, Node: Examples, Next: Unzcrash, Prev: File format, Up: Top 6 A small tutorial with examples ******************************** @@ -381,8 +400,8 @@ are abridged diagnostic messages from lziprecover). Example 6: Split the multi-member file `file.lz' and write each member -in its own `recXXXXXfile.lz' file. Then use `lziprecover -t' to test -the integrity of the resulting files. +in its own `recXXXfile.lz' file. Then use `lziprecover -t' to test the +integrity of the resulting files. lziprecover -s file.lz lziprecover -tv rec*file.lz @@ -401,7 +420,7 @@ error-checked merging of copies (*Note GNU ddrescue manual: mount -t iso9660 -o loop,ro cdimage2 /mnt/cdimage cp /mnt/cdimage/backup.tar.lz rescued2.tar.lz umount /mnt/cdimage - lziprecover -m -v -o rescued.tar.lz rescued1.tar.lz rescued2.tar.lz + lziprecover -m -v -o backup.tar.lz rescued1.tar.lz rescued2.tar.lz Example 8: Recover the first volume of those created with the command @@ -414,9 +433,80 @@ correct file produced is saved in `big_db_00001.lz'. Input files merged successfully -File: lziprecover.info, Node: Problems, Next: Concept Index, Prev: Examples, Up: Top +File: lziprecover.info, Node: Unzcrash, Next: Problems, Prev: Examples, Up: Top + +7 Testing the robustness of decompressors +***************************************** + +The lziprecover package also includes unzcrash, a program written to +test robustness to decompression of corrupted data, inspired by +unzcrash.c from Julian Seward's bzip2. Type `make unzcrash' in the +lziprecover source directory to build it. + + Unzcrash reads the specified file and then repeatedly decompresses +it, increasing 256 times each byte of the compressed data, so as to +test all possible one-byte errors. This should not cause any invalid +memory accesses. If it does, please, report it as a bug. + + Unzcrash really executes as a subprocess the shell command specified +in the first non-option argument, and then writes the file specified in +the second non-option argument to the standard input of the subprocess, +modifying the corresponding byte each time. Therefore you can use +unzcrash to test any decompressor (not only lzip), or even other decoder +programs with a suitable command line syntax. + + The format for running unzcrash is: + + unzcrash [OPTIONS] "lzip -tv" FILENAME.lz + + Unzcrash supports the following options: + +`-h' +`--help' + Print an informative help message describing the options and exit. + +`-V' +`--version' + Print the version number of lziprecover on the standard output and + exit. + +`-b RANGE' +`--bits=RANGE' + Test N-bit errors only, instead of testing all the 255 wrong + values for each byte. `N-bit error' means any value differing from + the original value in N bit positions, not a value differing from + the original value in the bit position N. + The number of N-bit errors per byte (N = 1 to 8) is: 8 28 56 70 56 + 28 8 1 + Examples of RANGE: 1 1,2,3 1-4 1,3-5,8 1-3,5-8 + +`-p BYTES' +`--position=BYTES' + First byte position to test in the file. Defaults to 0. + +`-q' +`--quiet' + Quiet operation. Suppress all messages. + +`-s BYTES' +`--size=BYTES' + Number of byte positions to test. If not specified, the whole file + is tested. + +`-v' +`--verbose' + Verbose mode. + + + Exit status: 0 for a normal exit, 1 for environmental problems (file +not found, invalid flags, I/O errors, etc), 2 to indicate a corrupt or +invalid input file, 3 for an internal consistency error (eg, bug) which +caused unzcrash to panic. + + +File: lziprecover.info, Node: Problems, Next: Concept index, Prev: Unzcrash, Up: Top -7 Reporting Bugs +8 Reporting bugs **************** There are probably bugs in lziprecover. There are certainly errors and @@ -429,9 +519,9 @@ for all eternity, if not longer. by running `lziprecover --version'. -File: lziprecover.info, Node: Concept Index, Prev: Problems, Up: Top +File: lziprecover.info, Node: Concept index, Prev: Problems, Up: Top -Concept Index +Concept index ************* @@ -439,26 +529,28 @@ Concept Index * bugs: Problems. (line 6) * examples: Examples. (line 6) -* file format: File Format. (line 6) +* file format: File format. (line 6) * getting help: Problems. (line 6) * introduction: Introduction. (line 6) -* invoking: Invoking Lziprecover. (line 6) -* merging files: Merging Files. (line 6) -* repairing files: Repairing Files. (line 6) +* invoking: Invoking lziprecover. (line 6) +* merging files: Merging files. (line 6) +* repairing files: Repairing files. (line 6) +* unzcrash: Unzcrash. (line 6) Tag Table: -Node: Top231 -Node: Introduction1032 -Node: Invoking Lziprecover3052 -Node: Repairing Files8489 -Node: Merging Files9208 -Node: File Format10338 -Node: Examples12822 -Ref: ddrescue-example14024 -Node: Problems15134 -Node: Concept Index15684 +Node: Top228 +Node: Introduction1095 +Node: Invoking lziprecover3248 +Node: Repairing files8686 +Node: Merging files9405 +Node: File format11176 +Node: Examples13660 +Ref: ddrescue-example14860 +Node: Unzcrash15969 +Node: Problems18344 +Node: Concept index18894 End Tag Table |