82fed7d421cce987228d51bfb590daa6f2d578ad
[cumulus.git] / README
1            Cumulus: Efficient Filesystem Backup to the Cloud
2
3 How to Build
4 ------------
5
6 Dependencies:
7   - libuuid (sometimes part of e2fsprogs)
8   - sqlite3
9   - boto, the python interface to Amazon's Web Services (for S3 storage)
10     http://code.google.com/p/boto
11
12 Building should be a simple matter of running "make".  This will produce
13 an executable called "cumulus".
14
15
16 Setting up Backups
17 ------------------
18
19 Two directories are needed for backups: one for storing the backup
20 snapshots themselves, and one for storing bookkeeping information to go
21 with the backups.  In this example, the first will be "/cumulus", and
22 the second "/cumulus.db", but any directories will do.  Only the first
23 directory, /cumulus, needs to be stored somewhere safe.  The second is
24 only used when creating new snapshots, and is not needed when restoring.
25
26   1. Create the snapshot directory and the local database directory:
27         $ mkdir /cumulus /cumulus.db
28
29   2. Initialize the local database using the provided script schema.sql
30      from the source:
31         $ sqlite3 /cumulus.db/localdb.sqlite
32         sqlite> .read schema.sql
33         sqlite> .exit
34
35   3. If encrypting or signing backups with gpg, generate appropriate
36      keypairs.  The keys can be kept in a user keyring or in a separate
37      keyring just for backups; this example does the latter.
38         $ mkdir /cumulus.db/gpg; chmod 700 /cumulus.db/gpg
39         $ gpg --homedir /cumulus.db/gpg --gen-key
40             (generate a keypair for encryption; enter a passphrase for
41             the secret key)
42         $ gpg --homedir /cumulus.db/gpg --gen-key
43             (generate a second keypair for signing; for automatic
44             signing do not use a passphrase to protect the secret key)
45      Be sure to store the secret key needed for decryption somewhere
46      safe, perhaps with the backup itself (the key protected with an
47      appropriate passphrase).  The secret signing key need not be stored
48      with the backups (since in the event of data loss, it probably
49      isn't necessary to create future backups that are signed with the
50      same key).
51
52      To achieve better compression, the encryption key can be edited to
53      alter the preferred compression algorithms to list bzip2 before
54      zlib.  Run
55         $ gpg --homedir /cumulus.db/gpg --edit-key <encryption key>
56         Command> pref
57             (prints a terse listing of preferences associated with the
58             key)
59         Command> setpref
60             (allows preferences to be changed; copy the same preferences
61             list printed out by the previous command, but change the
62             order of the compression algorithms, which start with "Z",
63             to be "Z3 Z2 Z1" which stands for "BZIP2, ZLIB, ZIP")
64         Command> save
65
66     Copy the provided encryption filter program, cumulus-filter-gpg,
67     somewhere it may be run from.
68
69   4. Create a script for launching the Cumulus backup process.  A simple
70      version is:
71
72         #!/bin/sh
73         export LBS_GPG_HOME=/cumulus.db/gpg
74         export LBS_GPG_ENC_KEY=<encryption key>
75         export LBS_GPG_SIGN_KEY=<signing key>
76         cumulus --dest=/cumulus --localdb=/cumulus.db --scheme=test \
77             --filter="cumulus-filter-gpg --encrypt" --filter-extension=.gpg \
78             --signature-filter="cumulus-filter-gpg --clearsign" \
79             /etc /home /other/paths/to/store
80
81     Make appropriate substitutions for the key IDs and any relevant
82     paths.  Here "--scheme=test" gives a descriptive name ("test") to
83     this collection of snapshots.  It is possible to store multiple sets
84     of backups in the same directory, using different scheme names to
85     distinguish them.  The --scheme option can also be left out
86     entirely.
87
88
89 Backup Maintenance
90 ------------------
91
92 Segment cleaning must periodically be done to identify backup segments
93 that are mostly unused, but are storing a small amount of useful data.
94 Data in these segments will be rewritten into new segments in future
95 backups to eliminate the dependence on the almost-empty old segments.
96
97 The provided cumulus-util tool can perform the necessary cleaning.  Run
98 it with
99     $ cumulus-util --localdb=/cumulus.db clean
100 Cleaning is still under development, and so may be improved in the
101 future, but this version is intended to be functional.
102
103 Old backup snapshots can be pruned from the snapshot directory
104 (/cumulus) to recover space.  A snapshot which is still referenced by
105 the local database should not be deleted, however.  Deleting an old
106 backup snapshot is a simple matter of deleting the appropriate snapshot
107 descriptor file (snapshot-*.lbs) and any associated checksums
108 (snapshot-*.sha1sums).  Segments used by that snapshot, but not any
109 other snapshots, can be identified by running the clean-segments.pl
110 script from the /cumulus directory--this will perform a scan of the
111 current directory to identify unreferenced segments, and will print a
112 list to stdout.  Assuming the list looks reasonable, the segments can be
113 quickly deleted with
114     $ rm `./clean-segments.pl`
115 A tool to make this easier will be implemented later.
116
117 The clean-segments.pl script will also print out a warning message if
118 any snapshots appear to depend upon segments which are not present; this
119 is a serious error which indicates that some of the data needed to
120 recover a snapshot appears to be lost.
121
122
123 Listing and Restoring Snapshots
124 -------------------------------
125
126 A listing of all currently-stored snapshots (and their sizes) can be
127 produced with
128     $ cumulus-util --store=/cumulus list-snapshot-sizes
129
130 If data from a snapshot needs to be restored, this can be done with
131     $ cumulus-util --store=/cumulus restore-snapshot \
132         test-20080101T121500 /dest/dir <files...>
133 Here, "test-20080101T121500" is the name of the snapshot (consisting of
134 the scheme name and a timestamp; this can be found from the output of
135 list-snapshot-sizes) and "/dest/dir" is the path under which files
136 should be restored (this directory should initially be empty).
137 "<files...>" is a list of files or directories to restore.  If none are
138 specified, the entire snapshot is restored.
139
140
141 Remote Backups
142 --------------
143
144 The cumulus-util command can operate directly on remote backups.  The
145 --store parameter accepts, in addition to a raw disk path, a URL.
146 Supported URL forms are
147     file:///path        Equivalent to /path
148     s3://bucket/path    Storage in Amazon S3
149         (Expects the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
150         environment variables to be set appropriately)
151
152 To copy backup snapshots from one storage area to another, the
153 cumulus-sync command can be used, as in
154     $ cumulus-sync file:///cumulus s3://my-bucket/cumulus
155
156 Support for directly writing backups to a remote location (without using
157 a local staging directory and cumulus-sync) is slightly more
158 experimental, but can be achieved by replacing
159     --dest=/cumulus
160 with
161     --upload-script="cumulus-store s3://my-bucket/cumulus"
162
163
164 Alternate Restore Tool
165 ----------------------
166
167 The contrib/restore.pl script is a simple program for restoring the
168 contents of a Cumulus snapshot.  It is not as full-featured as the
169 restore functionality in cumulus-util, but it is far more compact.  It
170 could be stored with the backup files so a tool for restores is
171 available even if all other data is lost.
172
173 The restore.pl script does not know how to decompress segments, so this
174 step must be performed manually.  Create a temporary directory for
175 holding all decompressed objects.  Copy the snapshot descriptor file
176 (*.lbs) for the snapshot to be restored to this temporary directory.
177 The snapshot descriptor includes a list of all segments which are needed
178 for the snapshot.  For each of these snapshots, decompress the segment
179 file (with gpg or the appropriate program based on whatever filter was
180 used), then pipe the resulting data through "tar -xf -" to extract.  Do
181 this from the temporary directory; the temporary directory should be
182 filled with one directory for each segment decompressed.
183
184 Run restore.pl giving two arguments: the snapshot descriptor file
185 (*.lbs) in the temporary directory, and a directory where the restored
186 files should be written.