README

   1                   LBS: An LFS-Inspired Backup Solution
   2
   3 How to Build
   4 ------------
   5
   6 Dependencies:
   7   - libuuid
   8   - sqlite3
   9
  10 Building should be a simple matter of running "make".  This will produce
  11 an executable called "lbs".
  12
  13
  14 Setting up Backups
  15 ------------------
  16
  17 Two directories are needed for backups: one for storing the backup
  18 snapshots themselves, and one for storing bookkeeping information to go
  19 with the backups.  In this example, the first will be "/lbs", and the
  20 second "/lbs.db", but any directories will do.  Only the first
  21 directory, /lbs, needs to be stored somewhere safe.  The second is only
  22 used when creating new snapshots, and is not needed when restoring.
  23
  24   1. Create the snapshot directory and the local database directory:
  25         $ mkdir /lbs /lbs.db
  26
  27   2. Initialize the local database using the provided script schema.sql
  28      from the source:
  29         $ sqlite3 /lbs.db/localdb.sqlite
  30         sqlite> .read schema.sql
  31         sqlite> .exit
  32
  33   3. If encrypting or signing backups with gpg, generate appropriate
  34      keypairs.  The keys can be kept in a user keyring or in a separate
  35      keyring just for backups; this example does the latter.
  36         $ mkdir /lbs.db/gpg; chmod 700 /lbs.db/gpg
  37         $ gpg --homedir /lbs.db/gpg --gen-key
  38             (generate a keypair for encryption; enter a passphrase for
  39             the secret key)
  40         $ gpg --homedir /lbs.db/gpg --gen-key
  41             (generate a second keypair for signing; for automatic
  42             signing do not use a passphrase to protect the secret key)
  43      Be sure to store the secret key needed for decryption somewhere
  44      safe, perhaps with the backup itself (the key protected with an
  45      appropriate passphrase).  The secret signing key need not be stored
  46      with the backups (since in the event of data loss, it probably
  47      isn't necessary to create future backups that are signed with the
  48      same key).
  49
  50      To achieve better compression, the encryption key can be edited to
  51      alter the preferred compression algorithms to list bzip2 before
  52      zlib.  Run
  53         $ gpg --homedir /lbs.db/gpg --edit-key <encryption key>
  54         Command> pref
  55             (prints a terse listing of preferences associated with the
  56             key)
  57         Command> setpref
  58             (allows preferences to be changed; copy the same preferences
  59             list printed out by the previous command, but change the
  60             order of the compression algorithms, which start with "Z",
  61             to be "Z3 Z2 Z1" which stands for "BZIP2, ZLIB, ZIP")
  62         Command> save
  63
  64     Copy the provided encryption filter program, lbs-filter-gpg,
  65     somewhere it may be run from.
  66
  67   4. Create a script for launching the LBS backup process.  A simple
  68      version is:
  69
  70         #!/bin/sh
  71         export LBS_GPG_HOME=/lbs.db/gpg
  72         export LBS_GPG_ENC_KEY=<encryption key>
  73         export LBS_GPG_SIGN_KEY=<signing key>
  74         lbs --dest=/lbs --localdb=/lbs.db
  75             --filter="lbs-filter-gpg --encrypt" --filter-extension=.gpg \
  76             --signature-filter="lbs-filter-gpg --clearsign" \
  77             /etc /home /other/paths/to/store
  78
  79     Make appropriate substitutions for the key IDs and any relevant
  80     paths.  If desired, insert an option "--scheme=<name>" to specify a
  81     name for this backup scheme which will be included in the snapshot
  82     file names (for example, use a name based on the hostname or
  83     descriptive of the files backed up).
  84
  85
  86 Backup Maintenance
  87 ------------------
  88
  89 Segment cleaning must periodically be done to identify backup segments
  90 that are mostly unused, but are storing a small amount of useful data.
  91 Data in these segments will be rewritten into new segments in future
  92 backups to eliminate the dependence on the almost-empty old segments.
  93
  94 Segment cleaning is currently a mostly manual process.  An automatic
  95 tool for performing segment cleaning will be available in the future.
  96
  97 Old backup snapshots can be pruned from the snapshot directory (/lbs) to
  98 recover space.  Deleting an old backup snapshot is a simple matter of
  99 deleting the appropriate snapshot descriptor file (snapshot-*.lbs) and
 100 any associated checksums (snapshot-*.sha1sums).  Segments used by that
 101 snapshot, but not any other snapshots, can be identified by running the
 102 clean-segments.pl script from the /lbs directory--this will perform a
 103 scan of the current directory to identify unreferenced segments, and
 104 will print a list to stdout.  Assuming the list looks reasonable, the
 105 segments can be quickly deleted with
 106     $ rm `./clean-segments.pl`
 107
 108 The clean-segments.pl script will also print out a warning message if
 109 any snapshots appear to depend upon segments which are not present; this
 110 is a serious error which indicates that some of the data needed to
 111 recover a snapshot appears to be lost.
 112
 113
 114 Restoring a Snapshot
 115 --------------------
 116
 117 The restore.pl script is a simple (proof-of-concept, really) program for
 118 restoring the contents of an LBS snapshot.  Ideally, it should be stored
 119 with the backup files so it is available if it is needed.
 120
 121 The restore.pl script does not know how to decompress segments, so this
 122 step must be performed manually.  Create a temporary directory for
 123 holding all decompressed objects.  Copy the snapshot descriptor file
 124 (*.lbs) for the snapshot to be restored to this temporary directory.
 125 The snapshot descriptor includes a list of all segments which are needed
 126 for the snapshot.  For each of these snapshots, decompress the segment
 127 file (with gpg or the appropriate program based on whatever filter was
 128 used), then pipe the resulting data through "tar -xf -" to extract.  Do
 129 this from the temporary directory; the temporary directory should be
 130 filled with one directory for each segment decompressed.
 131
 132 Run restore.pl giving two arguments: the snapshot descriptor file
 133 (*.lbs) in the temporary directory, and a directory where the restored
 134 files should be written.
 135
 136 A better recovery tool will be provided in the future.