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

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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