[PATCH docs 4/5] qm: document snapshot operations

[Fiona Ebner <f.ebner@proxmox.com>]

Add a common intro for snapshots and hibernation to describe the
differences and commonalities.

Document why snapshots with multiple disks are consistent. There
already is a 'qm_snapshots' anchor, but that is a subsection for the
configuration chapter, so use 'qm_snapshot_operations' for the new
one.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
 qm.adoc | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 67 insertions(+), 4 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 93372c5..003cdc6 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -2127,9 +2127,67 @@ It will be called during various phases of the guests lifetime.
 For an example and documentation see the example script under
 `/usr/share/pve-docs/examples/guest-example-hookscript.pl`.
 
+[[qm_snapshots_and_hibernation]]
+Snapshots and Hibernation
+-------------------------
+
+You can use snapshots and hibernation to preserve the current state of the VM
+configuration, disks, device state and RAM. Hibernation stops and locks the VM
+and you can resume the VM from the saved state later. Snapshots allow the VM to
+continue running and being modified normally and you can rollback to a snapshot
+at any later time. Passing through host devices to the VM and certain other
+configuration settings might make preserving the state impossible and thus block
+snapshots and hibernation. Certain storages like RBD allow arbitrary snapshot
+trees, other storages like ZFS only allow linear snapshot chains and rollback to
+the latest snapshot. Check the list of xref:_storage_types[Storage Types]
+for snapshots support.
+
+[[qm_snapshot_operations]]
+Snapshots
+~~~~~~~~~
+
+Create a new snapshot of the current configuration and disk state with:
+
+----
+# qm snapshot ID SNAPSHOT_NAME
+----
+
+For a running VM, you may additionally include the device state and RAM with:
+
+----
+# qm snapshot ID SNAPSHOT_NAME --vmstate 1
+----
+
+This creates a new volume on the xref:qm_vmstatestorage[state storage] and
+allows to restore the live state of the VM upon rollback.
+
+NOTE: Proxmox VE ensures consistency between multiple disks by pausing the vCPUs
+and completing and flushing all pending IO via the QEMU block layer before the
+disk snapshots are created.
+
+Delete a snapshot with:
+
+----
+# qm delsnapshot ID SNAPSHOT_NAME
+----
+
+Roll back to a snapshot with:
+
+----
+# qm rollback ID SNAPSHOT_NAME
+----
+
+WARNING: Rollback destroys the current state of the VM (even if running) and
+disks!
+
+The VM configuration and the state of the VM disks are changed back to the point
+in time when the snapshot was taken. If the VM state is included in the
+snapshot, the VM is live after rollback and continues running from the point
+in time when the snapshot was taken.
+
 [[qm_hibernate]]
 Hibernation
------------
+~~~~~~~~~~~
 
 You can suspend a VM to disk with the GUI option `Hibernate` or with
 
@@ -2142,9 +2200,14 @@ and the VM gets stopped. On the next start, the memory content will be
 loaded and the VM can continue where it was left off.
 
 [[qm_vmstatestorage]]
-.State storage selection
-If no target storage for the memory is given, it will be automatically
-chosen, the first of:
+State storage selection
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To the save the RAM and device state of the virtual machine, a separate volume
+is created. For hibernation, use the `--statestorage` option to specify the
+target storage for the state volume. For snapshots or if not provided for
+hibernation, the target storage for the state volume is automatically chosen,
+the first of:
 
 1. The storage `vmstatestorage` from the VM config.
 2. The first shared storage from any VM disk.
-- 
2.47.3