Documentation/bup-damage.md

   1 % bup-damage(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   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 # OPTIONS
  28
  29 -n, \--num=*numblocks*
  30 :   the number of separate blocks to damage in each file
  31     (default 10).
  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`.
  36
  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
  46     size of one byte.
  47
  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.
  55
  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
  63     damage each time).
  64
  65 \--equal
  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
  72     `-s 1`.)
  73
  74 # EXAMPLES
  75     # make a backup in case things go horribly wrong
  76     cp -pPR ~/.bup/objects/pack ~/bup-packs.bak
  77
  78     # generate recovery blocks for all packs
  79     bup fsck -g
  80
  81     # deliberately damage the packs
  82     bup damage -n 10 -s 1 -S 0 ~/.bup/objects/pack/*.{pack,idx}
  83
  84     # recover from the damage
  85     bup fsck -r
  86
  87 # SEE ALSO
  88
  89 `bup-fsck`(1), `par2`(1)
  90
  91 # BUP
  92
  93 Part of the `bup`(1) suite.