api: Discourage use of VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE

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.

Encourage use of explicit virDomainFSFreeze/virDomainFSThaw.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>

diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c
index f856e5b9b83d6223483fd15f363a665f957917df..15bf4d86346b2a2d8ec391f118d5c1fa0a0ff1dd 100644 (file)
--- 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