27.04.2016 15:31, Daniel P. Berrange пишет:
On Fri, Apr 08, 2016 at 11:47:29PM +0300, Maxim Nestratov wrote:
Hello all,
Here is the first more detailed view on the list of the backup API functions
that
look reasonable to have. Though they are presented with parameters and short
description all these are the subject to discuss and I kindly ask you to
take a
look and comment. Your ideas and considerations are very welcome.
--------------------------------------------------------------------------------
virBackupPtr virDomainBackupCreateXML(virDomainPtr domain,
const char * xmlDesc,
unsigned int flags)
Nitpick, lets call it virDomainBackupPtr rather than just virBackupPtr.
Likewise use virDomainBackup as name prefix for other data types
and method names
Ok
Create a new backup of a domain based on the backup xml contained in
xmlDesc.
- domain: a domain object
- xmlDesc: string containing an XML description of the backup
- flags: bitwise-OR of virBackupCreateFlags
- returns: an opaque virBackupPtr on success or NULL on failure
enum virBackupCreateFlags {
to be defined
}
An example of backup xml:
<domainbackup>
<uuid>54c70d40-26bb-48cd-9639-b3a1e9adf650</uuid>
<description>Any string</description>
<parent>
<uuid>d2ee2566-bef2-408f-ac7a-eb8004186074</uuid>
<parent>
<disks>
<disk name='vda'>
<target>
... volume, file, or any possible target
</target>
</disk>
<disk name='vdb'>
<target>
...
</target>
</disk>
</disks>
</domainbackup>
--------------------------------------------------------------------------------
virBackupPtr virBackupStartUnmanaged(virDomainPtr domain,
const char * xmlDesc,
unsigned int flags)
Start a new unmanaged backup of a domain based on the backup xml contained
in
xmlDesc. This function starts 'blockdev-backup' QMP command to block
devices
exposed as nbd servers by qemu. It is for 3d party managed backups.
- domain: a domain object
- xmlDesc: string containing an XML description of the backup
- flags: bitwise-OR of virBackupCreateFlags
- returns: an opaque virBackupPtr on success or NULL on failure
An example of backup xml:
<domainbackup>
<uuid>54c70d40-26bb-48cd-9639-b3a1e9adf650</uuid>
<description>Any string</description>
<disks>
<disk name='hda'>
<target>
... nbd server parameters for 'nbd-server-start' command
followed by
'blockdev-backup' and 'nbd-server-add' QMP commands
OR some other suitable target
</target>
</disk>
<disk name='hdb'>
<target>
... nbd server parameters
</target>
</disk>
</disks>
</domainbackup>
I'm assuming an 'unmanaged' backup would not be shown when calling
virDomainBackupList later on ?
Exactly
Also with the QEMU built-in NBD server, you just have a single
nbd-server-start to do, and that one server will export multiple
disks as named exports. So you wouldn't repeat the NBD server
parameters for all disks.
Got it.
--------------------------------------------------------------------------------
int virDomainBackupList(virDomainPtr domain,
virBackupPtr ** backups,
unsigned int flags)
Collect the list of domain backups for the given domain, and allocate an
array
to store those objects
- domain: a domain object
- backups: pointer to variable to store the array containing backup
objects,
or NULL if the list is not required (just returns number of backups)
- flags: bitwise-OR of virBackupListFlags
- returns: the number of backups on success or -1 on failure
enum virBackupListFlags {
VIR_BACKUP_LIST_FULL = 1,
VIR_BACKUP_LIST_LATEST = 2,
...
}
--------------------------------------------------------------------------------
int virBackupListChildren(virBackupPtr backup,
virBackupPtr ** backups,
unsigned int flags)
Collect the list of child backups for the given backup, and allocate an
array
to store them
- backup: a backup object
- backups: pointer to variable to store the array containing backup
objects,
or NULL if the list is not required (just returns number of backups)
- flags: bitwise-OR of virBackupListFlags
- returns: the number of backups on success or -1 on failure
--------------------------------------------------------------------------------
int virBackupRestore(const char * xmlDesc,
unsigned int flags)
For the "managed backups" case it feels like this should be accepting
a virDomainBackupPtr rather than an xmlDesc string.
Not sure because I would like to have an ability to restore not every
disk a backup has but sometimes selected only.
For the "unmanaged backups", then IIUC, we would need to have
a virDOmainPtr and the xmlDesc. So probably want a separate
API for that. virBackupRestoreUnmanaged ?
Makes sense.
Restore a domain from a given backup.
- xmlDesc: string containing an XML description of what to restore. It
can
repeate complete backup xml or specify some part of disks to restore.
- flags: bitwise-OR of virBackupRestoreFlags
- returns: 0 on success or -1 on failure
enum virBackupRestoreFlags {
VIR_BACKUP_RESTORE_NEW_DOMAIN = 1,
VIR_BACKUP_RESTORE_REWRITE_EXISTING_DISK = 2,
...
}
An example of restore xml:
<domainbackup>
<uuid>54c70d40-26bb-48cd-9639-b3a1e9adf650</uuid>
<disks>
<disk name='vda'>
<target>
... volume, file, or any possible target, (if absent, reuses
current
disk target)
</target>
</disk>
<disk name='vdb'>
<target>
...
</target>
</disk>
</disks>
</domainbackup>
--------------------------------------------------------------------------------
int virBackupDelete(virBackupPtr backup,
unsigned int flags)
Delete the specified backup
- backup: a backup object
- flags: bitwise-OR of virBackupDeleteFlags
- returns: 0 on success or -1 on failure
enum virBackupDeleteFlags {
VIR_BACKUP_DELETE_ALL = 1,
VIR_BACKUP_DELETE_ALL_CHILDREN = 2,
...
}
--------------------------------------------------------------------------------
int virBackupFree(virBackupPtr backup)
Free the backup object. The backup itself is not modified. The data
structure
is freed and should not be used thereafter.
- backup: a backup object
- returns: 0 on success or -1 on failure
--------------------------------------------------------------------------------
char* virBackupGetXMLDesc(virBackupPtr backup,
unsigned int flags)
Provide an XML description of the backup
- backup: a backup object
- flags: bitwise-OR of virDomainXMLFlags
- returns: a 0 terminated UTF-8 encoded XML instance, or NULL in case of
error. The caller must free() the returned value
An example of dumped xml:
<domainbackup>
<uuid>54c70d40-26bb-48cd-9639-b3a1e9adf650</uuid>
<creationTime>1270477159</creationTime>
<description>Any string</description>
<parent>
<uuid>d2ee2566-bef2-408f-ac7a-eb8004186074</uuid>
<parent>
<disks>
<disk name='vda'>
<target>
... volume, file, or any possible target
</target>
</disk>
<disk name='vdb'>
<target>
...
</target>
</disk>
</disks>
</domainbackup>
--------------------------------------------------------------------------------
virBackupPtr virBackupLookupByUUID(const char * uuid,
unsigned int flags)
Try to lookup a backup by its UUID
- uuid: a backup uuid
- flags: for future use
- returns: an opaque virBackupPtr on success or NULL on failure
--------------------------------------------------------------------------------
virDomainPtr virBackupGetDomain(virBackupPtr backup)
Provide the domain pointer associated with a backup. The reference counter
on
the domain is not increased by this call
- backup: a backup object
- returns: a domain object on success or NULL on failure
--------------------------------------------------------------------------------
int virBackupFinishJob(virBackupPtr backup,
unsigned int flags)
Finish async job associated with specified backup
- backup: a backup object
- flags: bitwise-OR of virBackupDeleteFlags
- returns: 0 on if the job for the specified backup was finished or
cancelled
successfully or -1 otherwise
enum virBackupFinishJobFlags {
VIR_BACKUP_FINISH_JOB_CANCEL = 1,
VIR_BACKUP_FINISH_JOB_CHECK = 2,
...
}
Probablt want a corresponding virBackupAbortJob too.
Makes sense as well
--------------------------------------------------------------------------------
int virBackupGetParameters(virBackupPtr backup,
virTypedParameterPtr params,
int * nparams,
unsigned int flags)
Get backup parameters. On input, @nparams gives the size of the @params
array;
on output, @nparams gives how many slots were filled with parameter
information, which might be less but will not exceed the input value
- backup: a backup object
- params: pointer to backup parameter object (return value, allocated by
the
caller)
- nparams: pointer to number of blkio parameters; input and output
- flags: for future use
- returns: 0 on success or -1 on failure
--------------------------------------------------------------------------------
int virDomainSetDefaultTarget(virDomainPtr domain,
const char * xmlDesc,
unsigned int flags)
Set default store target for backup, snapshot, managed saved state metadata
- domain: a domain object
- xmlDesc: string containing an XML description of the backup
- flags: bitwise-OR of virDomainDeviceModifyFlags
- returns: 0 on success or -1 on failure
Not sure I understand what this is doing, but probably not a big deal.
I was trying to addess what Eric Blake said in this thread earlier
regarding a default pool.
Also, virDomainUndefineFlagsValues should be expanded with
VIR_DOMAIN_UNDEFINE_BACKUP and virDomainUndefineFlags implementations should
take into account this flag when undefining domains.
Overall I think this looks like a reasonable API design to start
implementing.
Thanks a lot.
Will start shortly.
Regards,
Daniel
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list