Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
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
