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.
Category:XAPI
Category:XAPI Devel