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