Disk import/export APIs

Note: official APIs have been developed, merged and documented here: http://xapi-project.github.io/xen-api/snapshots.html

Note: these APIs are considered experimental and are subject to change. To provide feedback and/or query current status, email xen-api@lists.xenproject.org

What are these APIs for?

These APIs provide a safe and efficient method to import and export Virtual Disk image (VDI) data to and from a host running xapi. These APIs allow clients to efficiently backup and restore VM disks where only changed blocks are processed, rather than full disk images.

These APIs are present in the following xapi versions:

• TODO

To detect the presence of these APIs:

• TODO: either expose a capability or suggest a "try it and see" approach

Using the 'xe' CLI

Exporting a full disk image

The following command will export a VDI with uuid $VDI in vhd format to the local file 'full.vhd':

 xe vdi-export uuid=$VDI filename=full.vhd format=vhd  --progress

The vhd format can be *sparse*, so if there are unallocated blocks within the VDI which xapi is aware of, they will be omitted from the vhd therefore making the vhd smaller. This should work on all current vhd-based storage types (EXT, NFS)

The currently supported formats are:

• vhd
• raw

Exporting only block changes/deltas

Assuming you have taken a VDI snapshot with a command like:

 SNAPSHOT=$(xe vdi-snapshot uuid=$VDI)

You can export only the changes between the VDI and the snapshot with:

 xe vdi-export uuid=$VDI base=$SNAPSHOT filename=delta.vhd format=vhd --progress

This should be a lot quicker than a full export and the output file should be smaller.

The currently supported formats are:

• vhd

Note the 'vhd parent' field within delta.vhd will not directly reference 'full.vhd'.

Importing a full disk image

First create a fresh VDI to hold the data:

 RESTORE=$(xe vdi-create name-label=restore virtual-size=...)

Then import the blocks

 xe vdi-import uuid=$RESTORE filename=full.vhd format=vhd --progress

Importing only changed blocks/deltas

Import the changed blocks:

 xe vdi-import uuid=$RESTORE filename=delta.vhd format=vhd --progress

Using the XenAPI

The APIs are exposed as HTTP GET and HTTP PUT operations.

The client can authenticate either by supplying a 'session_id=<session ref>' query parameter, or (if testing on the command-line via curl/wget) HTTP basic authentication can be used.

A sophisticated client should create a Task and supply a 'task_id=<task ref>' query parameter, allowing the client to track progress and success/failure of the operation. Note the HTTP layer cannot provide application-level success/failure information as the 'HTTP 200 OK' has to be sent *before* the data has been uploaded or downloaded. Note a client which supplies its own Task is also responsible for cleaning it up afterwards with a Task.destroy.

Exporting a disk image (full or deltas)

 HTTP GET /export_raw_vdi?vdi=<VDI ref>[&session_id=<session ref>][&task_id=<task ref>][&format=<format>][&base=<base>]

where

• vdi: (required) the disk to export
• session_id: (optional) a logged in session. If not provided then the client must use basic auth.
• task_id: (optional) an existing task for tracking progress
• format: (optional) the output format to use
• base: (optional) if this parameter is present then only deltas will be generated.

Importing a disk image (full or deltas)

 HTTP PUT /import_raw_vdi?vdi=<VDI ref>[&session_id=<session ref>][&task_id=<task ref>][&format=<format>]

where

• vdi: (required) the disk to import
• session_id: (optional) a logged in session. If not provided then the client must use basic auth.
• task_id: (optional) an existing task for tracking progress
• format: (optional) the output format to use

It is not necessary to specify that the disk contains deltas-- this will be inferred from the input stream.