Documentation/bup-fsck.md

   1 % bup-fsck(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-fsck - verify or repair a bup repository
   8
   9 # SYNOPSIS
  10
  11 bup fsck [-r] [-g] [-v] [\--quick] [-j *jobs*] [\--par2-ok]
  12 [\--disable-par2] [filenames...]
  13
  14 # DESCRIPTION
  15
  16 `bup fsck` is a tool for validating bup repositories in the
  17 same way that `git fsck` validates git repositories.
  18
  19 It can also generate and/or use "recovery blocks" using the
  20 `par2`(1) tool (if you have it installed).  This allows you
  21 to recover from damaged blocks covering up to 5% of your
  22 `.pack` files.
  23
  24 In a normal backup system, damaged blocks are less
  25 important, because there tends to be enough data duplicated
  26 between backup sets that a single damaged backup set is
  27 non-critical.  In a deduplicating backup system like bup,
  28 however, no block is ever stored more than once, even if it
  29 is used in every single backup.  If that block were to be
  30 unrecoverable, *all* your backup sets would be
  31 damaged at once.  Thus, it's important to be able to verify
  32 the integrity of your backups and recover from disk errors
  33 if they occur.
  34
  35 *WARNING*: bup fsck's recovery features are not available
  36 unless you have the free `par2`(1) package installed on
  37 your bup server.
  38
  39 *WARNING*: bup fsck obviously cannot recover from a
  40 complete disk failure.  If your backups are important, you
  41 need to carefully consider redundancy (such as using RAID
  42 for multi-disk redundancy, or making off-site backups for
  43 site redundancy).
  44
  45 # OPTIONS
  46
  47 -r, \--repair
  48 :   attempt to repair any damaged packs using
  49     existing recovery blocks.  (Requires `par2`(1).)
  50
  51 -g, \--generate
  52 :   generate recovery blocks for any packs that don't
  53     already have them.  (Requires `par2`(1).)
  54
  55 -v, \--verbose
  56 :   increase verbosity (can be used more than once).
  57
  58 \--quick
  59 :   don't run a full `git verify-pack` on each pack file;
  60     instead just check the final checksum.  This can cause
  61     a significant speedup with no obvious decrease in
  62     reliability.  However, you may want to avoid this
  63     option if you're paranoid.  Has no effect on packs that
  64     already have recovery information.
  65
  66 -j, \--jobs=*numjobs*
  67 :   maximum number of pack verifications to run at a time.
  68     The optimal value for this option depends how fast your
  69     CPU can verify packs vs. your disk throughput.  If you
  70     run too many jobs at once, your disk will get saturated
  71     by seeking back and forth between files and performance
  72     will actually decrease, even if *numjobs* is less than
  73     the number of CPU cores on your system.  You can
  74     experiment with this option to find the optimal value.
  75
  76 \--par2-ok
  77 :   immediately return 0 if `par2`(1) is installed and
  78     working, or 1 otherwise.  Do not actually check
  79     anything.
  80
  81 \--disable-par2
  82 :   pretend that `par2`(1) is not installed, and ignore all
  83     recovery blocks.
  84
  85
  86 # EXAMPLES
  87     # generate recovery blocks for all packs that don't
  88     # have them
  89     bup fsck -g
  90
  91     # generate recovery blocks for a particular pack
  92     bup fsck -g ~/.bup/objects/pack/153a1420cb1c8*.pack
  93
  94     # check all packs for correctness (can be very slow!)
  95     bup fsck
  96
  97     # check all packs for correctness and recover any
  98     # damaged ones
  99     bup fsck -r
 100
 101     # check a particular pack for correctness and recover
 102     # it if damaged
 103     bup fsck -r ~/.bup/objects/pack/153a1420cb1c8*.pack
 104
 105     # check if recovery blocks are available on this system
 106     if bup fsck --par2-ok; then
 107         echo "par2 is ok"
 108     fi
 109
 110 # SEE ALSO
 111
 112 `bup-damage`(1), `fsck`(1), `git-fsck`(1)
 113
 114 # BUP
 115
 116 Part of the `bup`(1) suite.