[PATCH 3/3] kbase: Introduce 'snapshots' page and describe the new 'manual' snapshot

[Peter Krempa]

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/kbase/index.rst     |  3 +++
 docs/kbase/meson.build   |  1 +
 docs/kbase/snapshots.rst | 53 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 docs/kbase/snapshots.rst

diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst
index 09b19ed1af..77b23e96a8 100644
--- a/docs/kbase/index.rst
+++ b/docs/kbase/index.rst
@@ -55,6 +55,9 @@ Usage
 `Memory devices <memorydevices.html>`__
    Memory devices and their use

+`Snapshots <snapshots.html>`
+    Details about snapshotting a VM
+

 Internals / Debugging
 ---------------------
diff --git a/docs/kbase/meson.build b/docs/kbase/meson.build
index af067db453..d632f9bda1 100644
--- a/docs/kbase/meson.build
+++ b/docs/kbase/meson.build
@@ -18,6 +18,7 @@ docs_kbase_files = [
   'rpm-deployment',
   's390_protected_virt',
   'secureusage',
+  'snapshots',
   'systemtap',
   'virtiofs',
 ]
diff --git a/docs/kbase/snapshots.rst b/docs/kbase/snapshots.rst
new file mode 100644
index 0000000000..bc457197a0
--- /dev/null
+++ b/docs/kbase/snapshots.rst
@@ -0,0 +1,53 @@
+=========
+Snapshots
+=========
+
+.. contents::
+
+Manual storage snapshotting
+===========================
+
+Certain use cases such as block storage on LVM or disks backed via storage
+exported through the ``vhost-user-blk`` protocol may require that snapshots are
+done in conjunction with the storage provider which is not managed by **libvirt**.
+
+To achieve this such disks can use ``snapshot`` mode ``manual``. When a snapshot
+has a disk in manual mode the following happens:
+
+ #. ``libvirt`` takes snapshot of the VM memory if requested
+
+   #. If a live snapshot is requested (``VIR_DOMAIN_SNAPSHOT_CREATE_LIVE``) the
+      VM runs until the memory snapshot phase completes and is then paused.
+   #. Otherwise the VM is paused right away.
+
+ #. Snapshot of disks which are marked for external snapsot is executed
+ #. The API return success, the VM is paused.
+ #. The user snapshots the externally managed storage
+ #. The user resumes the execution of the VM (``virsh resume $VM``)
+
+*Note:* It's not required to wait until the API finishes. The snapshotting of
+``manual`` disks can be done right after a event of
+``VIR_DOMAIN_EVENT_ID_LIFECYCLE`` type with value of
+``VIR_DOMAIN_EVENT_SUSPENDED`` is emitted by libvirtd.
+
+Overview of manual snapshots
+----------------------------
+
+Manual snapshot of a disk is requested by setting the ``snapshot`` property to
+``manual`` in the snapshot XML ::
+
+  <domainsnapshot>
+    <memory file='/path/to/memory/img'/>
+    <disks>
+      <disk name='vda' snapshot='manual'/>
+      <disk name='vdb' snapshot='external'/>
+      <disk name='vdc' snapshot='no'/>
+    </disks>
+  </domainsnapshot>
+
+or ``--diskspec vda,snapshot=manual`` when using ``virsh snapshot-create-as``::
+
+  $ virsh snapshot-create-as  --diskspec vda,snapshot=manual \
+                              --diskspec vdb,snapshot=external \
+                              --diskspec vdc,snapshot=no $VM \
+                              --memspec file=/path/to/memory/img
-- 
2.35.1