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

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.


Best regards,
Maxim


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