Re: [libvirt] RFC backup API

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.