[PATCH 1/3] api: Discourage use of VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE

[Peter Krempa]

The flag creates additional points of failure which are hard to recover
from, such as when thawing of the filesystems fails after an otherwise
successful snapshot.

Encougage use of explicit virDomainFSFreeze/virDomainFSThaw.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 src/libvirt-domain-snapshot.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index f856e5b9b8..15bf4d8634 100644
--- a/src/libvirt-domain-snapshot.c
+++ b/src/libvirt-domain-snapshot.c
@@ -174,6 +174,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
  * file systems in use within domain OS. However, if the guest agent
  * is not present, an error is thrown. Moreover, this flag requires
  * VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY to be passed as well.
+ * For better control and error recovery users should invoke virDomainFSFreeze
+ * manually before taking the snapshot and then virDomainFSThaw to restore the
+ * VM rather than using VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE.
  *
  * By default, if the snapshot involves external files, and any of the
  * destination files already exist as a non-empty regular file, the
-- 
2.29.2