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 # EXAMPLE
  87
  88     # generate recovery blocks for all packs that don't
  89     # have them
  90     bup fsck -g
  91
  92     # generate recovery blocks for a particular pack
  93     bup fsck -g ~/.bup/objects/pack/153a1420cb1c8*.pack
  94
  95     # check all packs for correctness (can be very slow!)
  96     bup fsck
  97
  98     # check all packs for correctness and recover any
  99     # damaged ones
 100     bup fsck -r
 101
 102     # check a particular pack for correctness and recover
 103     # it if damaged
 104     bup fsck -r ~/.bup/objects/pack/153a1420cb1c8*.pack
 105
 106     # check if recovery blocks are available on this system
 107     if bup fsck --par2-ok; then
 108         echo "par2 is ok"
 109     fi
 110
 111 # SEE ALSO
 112
 113 `bup-damage`(1), `fsck`(1), `git-fsck`(1)
 114
 115 # BUP
 116
 117 Part of the `bup`(1) suite.