1 % bup-damage(1) Bup %BUP_VERSION%
2 % Avery Pennarun <apenwarr@gmail.com>
7 bup-damage - randomly destroy blocks of a file
11 bup damage [-n count] [-s maxsize] [--percent pct] [-S seed]
12 [--equal] <filenames...>
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.
20 *THIS PROGRAM IS EXTREMELY DANGEROUS AND WILL DESTROY YOUR
23 `bup damage` is primarily useful for automated or manual tests
24 of data recovery tools, to reassure yourself that the tools
30 : the number of separate blocks to damage in each file
32 Note that it's possible for more than one damaged
33 segment to fall in the same `bup-fsck`(1) recovery block,
34 so you might not damage as many recovery blocks as you
35 expect. If this is a problem, use `--equal`.
37 -s, --size=*maxblocksize*
38 : the maximum size, in bytes, of each damaged block
39 (default 1 unless `--percent` is specified). Note that
40 because of the way `bup-fsck`(1) works, a multi-byte
41 block could fall on the boundary between two recovery
42 blocks, and thus damaging two separate recovery blocks.
43 In small files, it's also possible for a damaged block
44 to be larger than a recovery block. If these issues
45 might be a problem, you should use the default damage
48 --percent=*maxblockpercent*
49 : the maximum size, in percent of the original file, of
50 each damaged block. If both `--size` and `--percent`
51 are given, the maximum block size is the minimum of the
52 two restrictions. You can use this to ensure that a
53 given block will never damage more than one or two
54 `git-fsck`(1) recovery blocks.
56 -S, --seed=*randomseed*
57 : seed the random number generator with the given value.
58 If you use this option, your tests will be repeatable,
59 since the damaged block offsets, sizes, and contents
60 will be the same every time. By default, the random
61 numbers are different every time (so you can run tests
62 in a loop and repeatedly test with different
66 : instead of choosing random offsets for each damaged
67 block, space the blocks equally throughout the file,
68 starting at offset 0. If you also choose a correct
69 maximum block size, this can guarantee that any given
70 damage block never damages more than one `git-fsck`(1)
71 recovery block. (This is also guaranteed if you use
76 # make a backup in case things go horribly wrong
77 cp -a ~/.bup/objects/pack ~/bup-packs.bak
79 # generate recovery blocks for all packs
82 # deliberately damage the packs
83 bup damage -n 10 -s 1 -S 0 ~/.bup/objects/pack/*.{pack,idx}
85 # recover from the damage
90 `bup-fsck`(1), `par2`(1)
94 Part of the `bup`(1) suite.