| 1 |
% bup-damage(1) Bup %BUP_VERSION% |
| 2 |
% Avery Pennarun <[email protected]> |
| 3 |
% %BUP_DATE% |
| 4 |
|
| 5 |
# NAME |
| 6 |
|
| 7 |
bup-damage - randomly destroy blocks of a file |
| 8 |
|
| 9 |
# SYNOPSIS |
| 10 |
|
| 11 |
bup damage [-n count] [-s maxsize] [\--percent pct] [-S seed] |
| 12 |
[\--equal] \<filenames...\> |
| 13 |
|
| 14 |
# DESCRIPTION |
| 15 |
|
| 16 |
Use `bup damage` to deliberately destroy blocks in a |
| 17 |
`.pack` or `.idx` file (from `.bup/objects/pack`) to test |
| 18 |
the recovery features of `bup-fsck`(1) or other programs. |
| 19 |
|
| 20 |
*THIS PROGRAM IS EXTREMELY DANGEROUS AND WILL DESTROY YOUR |
| 21 |
DATA* |
| 22 |
|
| 23 |
`bup damage` is primarily useful for automated or manual tests |
| 24 |
of data recovery tools, to reassure yourself that the tools |
| 25 |
actually work. |
| 26 |
|
| 27 |
Note that the details of the current behavior may change (particularly |
| 28 |
the details not documented here). For example the moment, the damage |
| 29 |
is strictly probabilistic, and so may or may not actually alter any |
| 30 |
given block. With a block size of 1, there should be a 1/256 chance |
| 31 |
that the block won't actually change. This behavior may change. |
| 32 |
|
| 33 |
# OPTIONS |
| 34 |
|
| 35 |
-n, \--num=*numblocks* |
| 36 |
: the number of separate blocks to damage in each file |
| 37 |
(default 10). |
| 38 |
Note that it's possible for more than one damaged |
| 39 |
segment to fall in the same `bup-fsck`(1) recovery block, |
| 40 |
so you might not damage as many recovery blocks as you |
| 41 |
expect. If this is a problem, use `--equal`. |
| 42 |
|
| 43 |
-s, \--size=*maxblocksize* |
| 44 |
: the maximum size, in bytes, of each damaged block |
| 45 |
(default 1 unless `--percent` is specified). Note that |
| 46 |
because of the way `bup-fsck`(1) works, a multi-byte |
| 47 |
block could fall on the boundary between two recovery |
| 48 |
blocks, and thus damaging two separate recovery blocks. |
| 49 |
In small files, it's also possible for a damaged block |
| 50 |
to be larger than a recovery block. If these issues |
| 51 |
might be a problem, you should use the default damage |
| 52 |
size of one byte. |
| 53 |
|
| 54 |
\--percent=*maxblockpercent* |
| 55 |
: the maximum size, in percent of the original file, of |
| 56 |
each damaged block. If both `--size` and `--percent` |
| 57 |
are given, the maximum block size is the minimum of the |
| 58 |
two restrictions. You can use this to ensure that a |
| 59 |
given block will never damage more than one or two |
| 60 |
`git-fsck`(1) recovery blocks. |
| 61 |
|
| 62 |
-S, \--seed=*randomseed* |
| 63 |
: seed the random number generator with the given value. |
| 64 |
If you use this option, your tests will be repeatable, |
| 65 |
since the damaged block offsets, sizes, and contents |
| 66 |
will be the same every time. By default, the random |
| 67 |
numbers are different every time (so you can run tests |
| 68 |
in a loop and repeatedly test with different |
| 69 |
damage each time). |
| 70 |
|
| 71 |
\--equal |
| 72 |
: instead of choosing random offsets for each damaged |
| 73 |
block, space the blocks equally throughout the file, |
| 74 |
starting at offset 0. If you also choose a correct |
| 75 |
maximum block size, this can guarantee that any given |
| 76 |
damage block never damages more than one `git-fsck`(1) |
| 77 |
recovery block. (This is also guaranteed if you use |
| 78 |
`-s 1`.) |
| 79 |
|
| 80 |
# EXAMPLES |
| 81 |
# make a backup in case things go horribly wrong |
| 82 |
cp -pPR ~/.bup/objects/pack ~/bup-packs.bak |
| 83 |
|
| 84 |
# generate recovery blocks for all packs |
| 85 |
bup fsck -g |
| 86 |
|
| 87 |
# deliberately damage the packs |
| 88 |
bup damage -n 10 -s 1 -S 0 ~/.bup/objects/pack/*.{pack,idx} |
| 89 |
|
| 90 |
# recover from the damage |
| 91 |
bup fsck -r |
| 92 |
|
| 93 |
# SEE ALSO |
| 94 |
|
| 95 |
`bup-fsck`(1), `par2`(1) |
| 96 |
|
| 97 |
# BUP |
| 98 |
|
| 99 |
Part of the `bup`(1) suite. |