From c6cde7cfe40bb036265d2095ded1a8c0f197ace4 Mon Sep 17 00:00:00 2001
From: Clark Boylan <clark.boylan@gmail.com>
Date: Thu, 5 Sep 2013 12:46:56 -0700
Subject: [PATCH] Add backup restore docs.

* doc/source/sysadmin.rst: Document how to restore from bup backups.

* modules/bup/files/etc/bup-excludes: Exclude special backup restore
dirs in /root. This prevents backup restores from being backed up
too.

Change-Id: Ide0e69c128be0a8b8774df7acaf9267df097f104
---
 doc/source/sysadmin.rst            | 38 ++++++++++++++++++++++++++++++
 modules/bup/files/etc/bup-excludes |  1 +
 2 files changed, 39 insertions(+)

diff --git a/doc/source/sysadmin.rst b/doc/source/sysadmin.rst
index eb61109453..f58cad3e65 100644
--- a/doc/source/sysadmin.rst
+++ b/doc/source/sysadmin.rst
@@ -226,6 +226,44 @@ Switching back to the server to be backed up, run::
 And verify the host key.  Add the "backup" class in puppet to the server
 to be backed up.
 
+Restore from Backup
+-------------------
+
+On the server that needs items restored from backup become root, start a
+screen session as restoring can take a while, and create a working
+directory to restore the backups into. This allows us to be selective in
+how we restore content from backups::
+
+  sudo su -
+  screen
+  mkdir /root/backup-restore-$DATE
+  cd /root/backup-restore-$DATE
+
+At this point we can join the tar that was split by the backup cron::
+
+  bup join -r bup-<short-servername>@ci-backup-rs-ord.openstack.org: root > backup.tar
+
+At this point you may need to wait a while. These backups are stored on
+servers geographically distant from our normal servers resulting in less
+network throughput between servers than we are used to.
+
+Once the ``bup join`` is complete you will have a tar archive of that
+backup. It may be useful to list the files in the backup
+``tar -tf backup.tar`` to get an idea of what things are available. At
+this point you will probably either want to extract the entire backup::
+
+  tar -xvf backup.tar
+  ls -al
+
+Or selectively extract files::
+
+  # path/to/file needs to match the output given by tar -t
+  tar -xvf backup.tar path/to/file
+
+Note if you created your working directory in a path that is not
+excluded by bup you will want to remove that directory when your work is
+done. /root/backup-restore-* is excluded so the path above is safe.
+
 Launching new servers
 =====================
 
diff --git a/modules/bup/files/etc/bup-excludes b/modules/bup/files/etc/bup-excludes
index 273a59341c..e9087a5e29 100644
--- a/modules/bup/files/etc/bup-excludes
+++ b/modules/bup/files/etc/bup-excludes
@@ -10,3 +10,4 @@
 /mnt/*
 /var/agentx/*
 /run/*
+/root/backup-restore-*