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