Replace boost::scoped_ptr with std::unique_ptr.

[cumulus.git] / README

diff --git a/README b/README
index 8a1be3c..2dec538 100644 (file)
--- a/README
+++ b/README
@@ -6,6 +6,13 @@ How to Build
 Dependencies:
   - libuuid (sometimes part of e2fsprogs)
   - sqlite3
+  - Python (2.7 or later, or 3.2 or later)
+  - Python six, a Python 2/3 compatibility library
+    https://pypi.python.org/pypi/six
+  - boto, the python interface to Amazon's Web Services (for S3 storage)
+    http://code.google.com/p/boto
+  - paramiko, SSH2 protocol for python (for sftp storage)
+    http://www.lag.net/paramiko/
 
 Building should be a simple matter of running "make".  This will produce
 an executable called "cumulus".
@@ -64,23 +71,24 @@ only used when creating new snapshots, and is not needed when restoring.
     Copy the provided encryption filter program, cumulus-filter-gpg,
     somewhere it may be run from.
 
-  4. Create a script for launching the LBS backup process.  A simple
+  4. Create a script for launching the Cumulus backup process.  A simple
      version is:
 
         #!/bin/sh
         export LBS_GPG_HOME=/cumulus.db/gpg
         export LBS_GPG_ENC_KEY=<encryption key>
         export LBS_GPG_SIGN_KEY=<signing key>
-        cumulus --dest=/cumulus --localdb=/cumulus.db
+        cumulus --dest=/cumulus --localdb=/cumulus.db --scheme=test \
             --filter="cumulus-filter-gpg --encrypt" --filter-extension=.gpg \
             --signature-filter="cumulus-filter-gpg --clearsign" \
             /etc /home /other/paths/to/store
 
     Make appropriate substitutions for the key IDs and any relevant
-    paths.  If desired, insert an option "--scheme=<name>" to specify a
-    name for this backup scheme which will be included in the snapshot
-    file names (for example, use a name based on the hostname or
-    descriptive of the files backed up).
+    paths.  Here "--scheme=test" gives a descriptive name ("test") to
+    this collection of snapshots.  It is possible to store multiple sets
+    of backups in the same directory, using different scheme names to
+    distinguish them.  The --scheme option can also be left out
+    entirely.
 
 
 Backup Maintenance
@@ -117,13 +125,61 @@ is a serious error which indicates that some of the data needed to
 recover a snapshot appears to be lost.
 
 
-Restoring a Snapshot
---------------------
-
-The contrib/restore.pl script is a simple (proof-of-concept, really)
-program for restoring the contents of an LBS snapshot.  Ideally, it
-should be stored with the backup files so it is available if it is
-needed.
+Listing and Restoring Snapshots
+-------------------------------
+
+A listing of all currently-stored snapshots (and their sizes) can be
+produced with
+    $ cumulus-util --store=/cumulus list-snapshot-sizes
+
+If data from a snapshot needs to be restored, this can be done with
+    $ cumulus-util --store=/cumulus restore-snapshot \
+        test-20080101T121500 /dest/dir <files...>
+Here, "test-20080101T121500" is the name of the snapshot (consisting of
+the scheme name and a timestamp; this can be found from the output of
+list-snapshot-sizes) and "/dest/dir" is the path under which files
+should be restored (this directory should initially be empty).
+"<files...>" is a list of files or directories to restore.  If none are
+specified, the entire snapshot is restored.
+
+
+Remote Backups
+--------------
+
+The cumulus-util command can operate directly on remote backups.  The
+--store parameter accepts, in addition to a raw disk path, a URL.
+Supported URL forms are
+    file:///path        Equivalent to /path
+    s3://bucket/path    Storage in Amazon S3
+        (Expects the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
+        environment variables to be set appropriately)
+    sftp://server/path  Storage on sftp server
+        (note that no password authentication or password protected
+        authorization keys are not supported atm and config options
+        like port or individual authorization keys are to be
+        configured in ~/.ssh/config and the public key of the
+        server has to be in ~/.ssh/known_hosts)
+
+To copy backup snapshots from one storage area to another, the
+cumulus-sync command can be used, as in
+    $ cumulus-sync file:///cumulus s3://my-bucket/cumulus
+
+Support for directly writing backups to a remote location (without using
+a local staging directory and cumulus-sync) is slightly more
+experimental, but can be achieved by replacing
+    --dest=/cumulus
+with
+    --upload-script="cumulus-store s3://my-bucket/cumulus"
+
+
+Alternate Restore Tool
+----------------------
+
+The contrib/restore.pl script is a simple program for restoring the
+contents of a Cumulus snapshot.  It is not as full-featured as the
+restore functionality in cumulus-util, but it is far more compact.  It
+could be stored with the backup files so a tool for restores is
+available even if all other data is lost.
 
 The restore.pl script does not know how to decompress segments, so this
 step must be performed manually.  Create a temporary directory for
@@ -139,6 +195,3 @@ filled with one directory for each segment decompressed.
 Run restore.pl giving two arguments: the snapshot descriptor file
 (*.lbs) in the temporary directory, and a directory where the restored
 files should be written.
-
-The cumulus-util program also now has some support for restoring
-snapsots (documentation coming soon).