[libvirt] RFC backup API
Maxim Nestratov
mnestratov at virtuozzo.com
Tue Apr 26 23:00:22 UTC 2016
08.04.2016 23:47, Maxim Nestratov пишет:
> 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)
>
> 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>
>
>
> --------------------------------------------------------------------------------
>
> 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)
>
> 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,
> ...
> }
>
>
> --------------------------------------------------------------------------------
>
> 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
>
>
> Also, virDomainUndefineFlagsValues should be expanded with
> VIR_DOMAIN_UNDEFINE_BACKUP and virDomainUndefineFlags implementations
> should
> take into account this flag when undefining domains.
>
>
> Best regards,
> Maxim
>
> --
> libvir-list mailing list
> libvir-list at redhat.com
> https://www.redhat.com/mailman/listinfo/libvir-list
Any chances to get comments on that?
More information about the libvir-list
mailing list