Re: RFC backup API

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

> 
>  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 ?

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.

> --------------------------------------------------------------------------------
> 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.

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 ?


> 
>  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.

> 
> 
> --------------------------------------------------------------------------------
> 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.

> 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.

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list



[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]