README

   1
   2 bup 0.01: It backs things up
   3 ============================
   4
   5 bup is a program that backs things up.  It's short for "backup." Can you
   6 believe that nobody else has named an open source program "bup" after all
   7 this time?  Me neither.
   8
   9 Despite its unassuming name, bup is pretty cool.  To give you an idea of
  10 just how cool it is, I wrote you this poem:
  11
  12                              Bup is teh awesome
  13                           What rhymes with awesome?
  14                             I guess maybe possum
  15                            But that's irrelevant.
  16
  17 Hmm.  Did that help?  Maybe prose is more useful after all.
  18
  19
  20 Reasons bup is awesome
  21 ----------------------
  22
  23 bup has a few advantages over other backup software:
  24
  25  - It uses a rolling checksum algorithm (similar to rsync) to split large
  26    files into chunks.  The most useful result of this is you can backup huge
  27    virtual machine (VM) disk images, databases, and XML files incrementally,
  28    even though they're typically all in one huge file, and not use tons of
  29    disk space for multiple versions.
  30
  31  - It uses the packfile format from git (the open source version control
  32    system), so you can access the stored data even if you don't like bup's
  33    user interface.
  34
  35  - Unlike git, it writes packfiles *directly* (instead of having a separate
  36    garbage collection / repacking stage) so it's fast even with gratuitously
  37    huge amounts of data.
  38
  39  - Data is "automagically" shared between incremental backups without having
  40    to know which backup is based on which other one - even if the backups
  41    are made from two different computers that don't even know about each
  42    other.  You just tell bup to back stuff up, and it saves only the minimum
  43    amount of data needed.
  44
  45  - Even when a backup is incremental, you don't have to worry about
  46    restoring the full backup, then each of the incrementals in turn; an
  47    incremental backup *acts* as if it's a full backup, it just takes less
  48    disk space.
  49
  50  - It's written in python (with some C parts to make it faster) so it's easy
  51    for you to extend and maintain.
  52
  53
  54 Reasons you might want to avoid bup
  55 -----------------------------------
  56
  57  - This is version 0.01.  What that means is this is the very first version.
  58    Therefore it will most probably not work for you, but we don't know why.
  59
  60  - It requires python 2.5, a C compiler, and an installed git version >= 1.5.2.
  61
  62  - It only works on Linux (for now).
  63
  64  - It has almost no documentation.  Not even a man page!  This file is all
  65    you get for now.
  66
  67
  68 Getting started
  69 ---------------
  70
  71  - check out the bup source code using git:
  72
  73         git clone git://github.com/apenwarr/bup
  74
  75  - install the python 2.5 development libraries.  On Debian or Ubuntu, this
  76    is:
  77         apt-get install python2.5-dev
  78
  79  - build the python module and symlinks:
  80
  81         make
  82
  83  - run the tests:
  84
  85         make test
  86
  87    (The tests should pass.  If they don't pass for you, stop here and send
  88    me an email.)
  89
  90  - Try making a local backup:
  91
  92         tar -cvf - /etc | bup split -n local-etc -vv
  93
  94  - Try restoring your backup:
  95
  96         bup join local-etc | tar -tf -
  97
  98  - Look at how much disk space your backup took:
  99
 100         du -s ~/.bup
 101
 102  - Make another backup (which should be mostly identical to the last one;
 103    notice that you don't have to *specify* that this backup is incremental,
 104    it just saves space automatically):
 105
 106         tar -cvf - /etc | bup split -n local-etc -vv
 107
 108  - Look how little extra space your second backup used on top of the first:
 109
 110         du -s ~/.bup
 111
 112  - Restore your old backup again (the ~1 is git notation for "one older than
 113    the most recent"):
 114
 115         bup join local-etc~1 | tar -tf -
 116
 117  - get a list of your previous backups:
 118
 119         GIT_DIR=~/.bup git log local-etc
 120
 121  - make a backup on a remote server (which must already have the 'bup' command
 122    somewhere in the PATH, and be accessible via ssh; make sure to replace
 123    SERVERNAME with the actual hostname of your server):
 124
 125         tar -cvf - /etc | bup split -r SERVERNAME: -n local-etc -vv
 126
 127  - try restoring the remote backup:
 128
 129         bup join -r SERVERNAME: local-etc | tar -tf -
 130
 131 That's all there is to it!
 132
 133
 134 How it works
 135 ------------
 136
 137 bup stores its data in a git-formatted repository.  Unfortunately, git
 138 itself doesn't actually behave very well for bup's use case (huge numbers of
 139 files, files with huge sizes, retaining file permissions/ownership are
 140 important), so we mostly don't use git's *code* except for a few helper
 141 programs.  For example, bup has its own git packfile writer written in
 142 python.
 143
 144 Basically, 'bup split' reads the data on stdin (or from files specified on
 145 the command line), breaks it into chunks using a rolling checksum (similar to
 146 rsync), and saves those chunks into a new git packfile.  There is one git
 147 packfile per backup.
 148
 149 When deciding whether to write a particular chunk into the new packfile, bup
 150 first checks all the other packfiles that exist to see if they already have that
 151 chunk.  If they do, the chunk is skipped.
 152
 153 git packs come in two parts: the pack itself (*.pack) and the index (*.idx).
 154 The index is pretty small, and contains a list of all the objects in the
 155 pack.  Thus, when generating a remote backup, we don't have to have a copy
 156 of the packfiles from the remote server: the local end just downloads a copy
 157 of the server's *index* files, and compares objects against those when
 158 generating the new pack, which it sends directly to the server.
 159
 160 The "-n" option to 'bup split' and 'bup save' is the name of the backup you
 161 want to create, but it's actually implemented as a git branch.  So you can
 162 do cute things like checkout a particular branch using git, and receive a
 163 bunch of chunk files corresponding to the file you split.
 164
 165 If you use '-b' or '-t' or '-c' instead of '-n', bup split will output a
 166 list of blobs, a tree containing that list of blobs, or a commit containing
 167 that tree, respectively, to stdout.  You can use this to construct your own
 168 scripts that do something with those values.
 169
 170 'bup save' basically just runs 'bup split' a whole bunch of times, once per
 171 file in a directory hierarchy, and assembles a git tree that contains all
 172 the resulting objects.  Among other things, that makes 'git diff' much more
 173 useful (compared to splitting a tarball, which is essentially a big binary
 174 blob).  However, since bup splits large files into smaller chunks, the
 175 resulting tree structure doesn't *exactly* correspond to what git itself
 176 would have stored.  Also, the tree format used by 'bup save' will probably
 177 change in the future to support storing file ownership, more complex file
 178 permissions, and so on.
 179
 180
 181 Things that are stupid for now but which we'll fix later
 182 --------------------------------------------------------
 183
 184 Help with any of these problems, or others, is very, very welcome.  Let me
 185 know if you'd like to help.  Maybe we can start a mailing list.
 186
 187  - bup's incremental backup algorithm is braindead.
 188
 189    Bup reads the contents of every single file you want to back up, *then*
 190    it checks if it has that content already, and if not, it backs up the
 191    file.  Now, it happens to do that very fast (using mmap'ed git packfile
 192    indexes), all things considered, but it's not nearly as fast as simply
 193    noticing that the file inode+ctime is the same as before and just
 194    skipping it.  There's nothing preventing us from adding this
 195    optimization, though.  (Perhaps we could use the git indexfile format for
 196    tracking this?)
 197
 198  - 'bup save' is incomplete and there's no 'bup restore' yet.
 199
 200    'bup save' is supposed to recursively go through a given directory and
 201    store all the files efficiently, and then you could use 'bup restore' to
 202    restore all or some of them.  However, these features don't really work
 203    yet.
 204
 205    Instead, for now the best way to use bup is to feed 'bup split' a big tar
 206    file of your backup, then restore that tar file later with 'bup join'.
 207    This is cute, but inefficient; for example, tar files don't have an
 208    index, so to restore a single file would require linearly reading through
 209    the entire tarball.  (This is exactly like what always happens when you
 210    make a backup using tar, but if we use git's native trees/blobs the way
 211    they're meant to be used, it will be ridiculously faster.)
 212
 213  - bup could use inotify for *really* efficient incremental backups.
 214
 215    You could even have your system doing "continuous" backups: whenever a
 216    file changes, we immediately send an image of it to the server.  We could
 217    give the continuous-backup process a really low CPU and I/O priority so
 218    you wouldn't even know it was running.
 219
 220  - bup currently has no features that prune away *old* backups.
 221
 222    Because of the way the packfile system works, backups become "entangled"
 223    in weird ways and it's not actually possible to delete one pack
 224    (corresponding approximately to one backup) without risking screwing up
 225    other backups.
 226
 227    git itself has lots of ways of optimizing this sort of thing, but its
 228    methods aren't really applicable here; bup packfiles are just too huge.
 229    We'll have to do it in a totally different way.  There are lots of
 230    options.  For now: make sure you've got lots of disk space :)
 231
 232  - bup doesn't ever validate existing backups/packs to ensure they're
 233    correct.
 234
 235    This would be easy to implement (given that git uses hashes and CRCs all
 236    over the place), but nobody has implemented it.  For now, you could try
 237    doing a test restore of your tarball; doing so should trigger git's error
 238    handling if any of the objects are corrupted.
 239
 240  - bup has never been tested on anything but Linux.
 241
 242    There's nothing that makes it *inherently* non-portable, though, so
 243    that's mostly a matter of someone putting in some effort.
 244
 245
 246 How you can help
 247 ----------------
 248
 249 bup is a work in progress and there are many ways it can still be improved.
 250 If you'd like to contribute, please email me at <apenwarr@gmail.com>.  If
 251 enough people are interested, perhaps we should start a mailing list for
 252 it!
 253
 254 Have fun,
 255
 256 Avery
 257 January 2010