Debian Codegraph @

Documentation/man4/man7/man2/man3/man5/man2/bup-damage.1.md

raw
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.