On 8/23/22 6:32 AM, Peter Krempa wrote:
Checkpoints created via virDomainCheckpointCreateXML are generally not very useful as they need to be coupled with a backup.
Add a disclaimer to the docs explaining why users should use virDomainBackupBegin instead.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain-checkpoint.c | 10 ++++++++++ 1 file changed, 10 insertions(+)
diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index de747aff01..078e999bf3 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -142,6 +142,16 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * present, an error is thrown. This flag is incompatible with * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE. * + * Note: A checkpoint represent s point in time since which blocks changed by + * the hypervisor are tracked.
extra space in "represent s" Also, I think it would be more clearly understood if we changed "since" to "after". "Note: a checkpoint represents a point in time after which blocks changed..."
This means that + * for a checkpoint to be generally usable for doing an incremental backup it's + * required to perform a backup at the same time as taking the checkpoint.
I might suggest something like: "The main purpose of checkpoints is to enable incremental backups. But for a checkpoint to be useful for this purpose, a backup should be performed at the same time as the checkpoint is created."
+ * This is done via the virDomainBackupBegin API, which also allows to create + * a checkpoint at the same time. virDomainCheckpointCreateXML is generally not + * useful for creating checkpoints but rather only for re-creating the libvirt + * metadata.
my suggestion here: "This is done via the virDomainBackupBegin API, which also allows to create a checkpoint at the same time. Creating checkpoints with virDomainCheckpointCreateXML is generally only useful for re-creating the libvirt metadata" Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>