[sheepdog] [PATCH 6/9] Doc. "Sheepdog Advanced" add chapter "snapshots"

[Valerio Pachera]

Signed-off-by: Valerio Pachera <sirio81 at gmail.com>
---
 doc/snapshot.rst |  182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 doc/snapshot.rst

diff --git a/doc/snapshot.rst b/doc/snapshot.rst
new file mode 100644
index 0000000..9887aef
--- /dev/null
+++ b/doc/snapshot.rst
@@ -0,0 +1,182 @@
+Snapshot Backup And Restore
+===========================
+
+The purpose of taking snapshots is to have data frozen in a specific date/time
+period.
+
+Snapshots:
+    * can be taken while the guest is running;
+    * the operation is instantaneous (except for cache flushing);
+    * you can also access/backup/clone them while the guest is running;
+    * their number is limited to cluster available space only;
+    * they are associated by an id and (optionally) by a tag.
+    
+Common Operation
+****************
+
+::
+
+    # Create
+    dog vdi snapshot wheezy
+    
+    # Crate and associate a tag
+    dog vdi snapshot -s pre_upgrade wheezy
+    
+    # Show them
+    dog vdi list
+    
+    s wheezy     1   10 GB  1.8 GB  0.0 MB 2013-08-29 16:34   5ddf88     2         
+    s wheezy     2   10 GB  1.0 GB 1008 MB 2013-08-29 16:36   5ddf98     2           pre_upgrade
+    wheezy     0   10 GB  128 MB  1.9 GB 2013-08-29 16:55   5ddf99     2
+
+    # Delete a specific snapshot
+    dog delete -s monday wheezy
+    or
+    dog delete -s 2 wheezy
+    
+Roll Back
+*********
+
+| Consider the scenario of a single vdi named *'win7'* with snapshot taken every
+  day at 23:00.
+| Snapshots tag are *mon; tue; wed; thu.
+
+*Note: For illustrative purpose we don't consider the use of sheepfs.*
+
+Friday you notice your guest is not working well because of a virus infection
+it got Tuesday.
+
+You wish to:
+    * restore the guest as of Monday;
+    * restore your latest data;
+    * restore some file that got delete by the virus (you had them Thursday but
+      not Friday).
+
+First, re-start you guest using a iso (live cd) and save your latest data by
+network.
+
+Power off your guest, then
+
+::
+
+    dog vdi rollback -s thu win7
+    
+Start the guest again from an iso an copy the data you needed from Thursday
+by network.
+
+*Notice that win7 id 0 got erased, so you lost Friday useless data.*
+
+You can now restore win7 as of Monday:
+
+::
+
+    dog vdi rollback -s mon win7
+    
+*Notice that you didn't loose the other snapshot and you can always roll back to them!*
+
+Now start your "clean" guest and copy back the data.
+
+Once done, it's a good idea to take a snapshot, so we have the latest data and
+the "clean" guest.
+
+::
+
+    dog vdi snapshot -s fri_clean win7
+
+Clone
+*****
+
+Another one step solution, was:
+
+    * roll back win7 vdi to Monday snapshot;
+    * clone Thursday snapshot
+    
+::
+
+    dog vdi rallback -s mon win7
+    dog vdi clone -s thu win7clone
+    
+    # start the guest with bot drives
+    qemu-system-x86_64 -drive file=sheepdog:win7 -drive file=win7clone ... other options ...
+    
+Notice that cloning
+
+    * can be done only from a snapshot (you can't clone id 0)
+    * it's instantaneous
+
+This way your guest is up and running, and all you have to do is copy the data you need from the second disk (minding the virus).
+
+Backup
+******
+
+Note: need testing
+
+By backup we mean to copy data out of the cluster to another media (e.g. nas).
+Snapshot are not consider as backup.
+
+We consider the situation of a big vdi (named *mailserver*) that we wish to be
+able to restore in case of a disaster recovery.
+
+Snapshot are taken every day as in the previous example.
+
+| Sunday we create a full copy of the vdi.
+| This requires long time and space and we can't repeat that every day.
+| Consider also that vdi doesn't change so much between one day and the
+  next (say 2G).
+
+::
+
+    # Full backup of Sunday (23:00)
+    qemu-img convert -O qcow2 sheepdog:mailserver /media/nas/mailserver.qcow2
+    # Monday
+    dog vdi snapshot -s mon mailserver
+    # Tuesday
+    dog vdi backup -F sun -s mon > /media/nas/mailserver_mon.img
+    # at 23:00
+    dog vdi snapshot -s tue mailserver
+    # and so on till Friday
+    
+Restore
+*******
+
+In the worst case scenario, we format the cluster and we have to restore
+*mailserver* as of Friday
+
+::
+
+    dog cluster format
+    # Import mailserver as of Sunday
+    qemu-img convert -f qcow2 /media/nas/mailserver.qcow2 sheepdog:mailserver
+    # Restore incremental backup
+    dog vdi restore -s mon mailserver < /media/nas/mailserver_mon.img
+    # And so on
+    
+Cluser Snapshot
+***************
+
+| You may think that this command simply create a snapshot for all vdi.
+| You are WRONG!
+
+'cluster snapshot' is used to export "all" the content of the cluster in a
+folder, so out of the cluster. This is unlike vdi snapshot!
+
+**IMPORTANT:** vdi that has no snapshot will be **ignored**!
+
+In this example, there are the steps to follow:
+
+    # create a snapshot off all vdi you wish to backup.
+    dog vdi snaphost debian
+    dog vdi snaphost win7
+    ...
+    
+    # Save the snaphost
+    dog vdi snapshot save allmynicevdi /media/nas/cluster_snapshots
+    
+| 'allmynicevdi' is just a label/tag.    
+| Restore is also very simple.
+| Having a new formatted cluster, run
+
+    # Choose the snaphost you wish to restore
+    dog vdi snapshot list /media/nas/cluster_snapshots
+    # Load it
+    dog vdi snapshot load allmynicevdi /media/nas/cluster_snapshots
\ No newline at end of file
-- 
1.7.10.4