|
| 1 | +--- |
| 2 | +title: VM import/export |
| 3 | +layout: default |
| 4 | +--- |
| 5 | + |
| 6 | +VMs can be exported to a file and later imported to any XenServer host. The export protocol is a simple HTTP(S) GET, which should be performed on the master if the VM is on a pool member. Authorization is either standard HTTP basic authentication, or if a session has already been obtained, this can be used. The VM to export is specified either by UUID or by reference. To keep track of the export, a task can be created and passed in using its reference. The request might result in a redirect if the VM's disks are only accessible on a pool member. |
| 7 | + |
| 8 | +The following arguments are passed on the command line: |
| 9 | + |
| 10 | +Argument | Description |
| 11 | +------------|--------------------------------------------------------- |
| 12 | +session_id | the reference of the session being used to authenticate; required only when not using HTTP basic authentication |
| 13 | +task_id | the reference of the task object with which to keep track of the operation; optional, required only if you have created a task object to keep track of the export |
| 14 | +ref | the reference of the VM; required only if not using the UUID |
| 15 | +uuid | the UUID of the VM; required only if not using the reference |
| 16 | + |
| 17 | + |
| 18 | +For example, using the Linux command line tool cURL: |
| 19 | + |
| 20 | +```sh |
| 21 | +$ curl http://root:foo@myxenserver1/export?uuid=<vm_uuid> -o <exportfile> |
| 22 | +``` |
| 23 | + |
| 24 | +will export the specified VM to the file `exportfile`. |
| 25 | + |
| 26 | +To export just the metadata, use the URI `http://server/export_metadata`. |
| 27 | + |
| 28 | +The import protocol is similar, using HTTP(S) PUT. The `session_id` and `task_id` arguments are as for the export. The `ref` and `uuid` are not used; a new reference and uuid will be generated for the VM. There are some additional parameters: |
| 29 | + |
| 30 | +Argument | Description |
| 31 | +------------|--------------------------------------------------------- |
| 32 | +restore | if `true`, the import is treated as replacing the original VM - the implication of this currently is that the MAC addresses on the VIFs are exactly as the export was, which will lead to conflicts if the original VM is still being run. |
| 33 | +force | if `true`, any checksum failures will be ignored (the default is to destroy the VM if a checksum error is detected) |
| 34 | +sr_id | the reference of an SR into which the VM should be imported. The default behavior is to import into the `Pool.default_SR` |
| 35 | + |
| 36 | +For example, again using cURL: |
| 37 | + |
| 38 | +```sh |
| 39 | +curl -T <exportfile> http://root:foo@myxenserver2/import |
| 40 | +``` |
| 41 | + |
| 42 | +will import the VM to the default SR on the server. |
| 43 | + |
| 44 | +> **Note** |
| 45 | +> |
| 46 | +> Note that if no default SR has been set, and no `sr_uuid` is specified, the error message `DEFAULT_SR_NOT_FOUND` is returned. |
| 47 | +
|
| 48 | +Another example: |
| 49 | + |
| 50 | +```sh |
| 51 | +curl -T <exportfile> http://root:foo@myxenserver2/import?sr_id=<ref_of_sr> |
| 52 | +``` |
| 53 | + |
| 54 | +will import the VM to the specified SR on the server. |
| 55 | + |
| 56 | +To import just the metadata, use the URI `http://server/import_metadata` |
| 57 | + |
| 58 | +Legacy VM Import Format |
| 59 | +======================= |
| 60 | + |
| 61 | +This section describes the legacy VM import/export format and is for historical |
| 62 | +interest only. It should be updated to describe the current format, see |
| 63 | +[issue 64](https://github.com/xapi-project/xapi-project.github.io/issues/64) |
| 64 | + |
| 65 | + |
| 66 | +Xapi supports a human-readable legacy VM input format called XVA. This section describes the syntax and structure of XVA. |
| 67 | + |
| 68 | +An XVA consists of a directory containing XML metadata and a set of disk images. A VM represented by an XVA is not intended to be directly executable. Data within an XVA package is compressed and intended for either archiving on permanent storage or for being transmitted to a VM server - such as a XenServer host - where it can be decompressed and executed. |
| 69 | + |
| 70 | +XVA is a hypervisor-neutral packaging format; it should be possible to create simple tools to instantiate an XVA VM on any other platform. XVA does not specify any particular runtime format; for example disks may be instantiated as file images, LVM volumes, QCoW images, VMDK or VHD images. An XVA VM may be instantiated any number of times, each instantiation may have a different runtime format. |
| 71 | + |
| 72 | +XVA does not: |
| 73 | + |
| 74 | +- specify any particular serialization or transport format |
| 75 | + |
| 76 | +- provide any mechanism for customizing VMs (or templates) on install |
| 77 | + |
| 78 | +- address how a VM may be upgraded post-install |
| 79 | + |
| 80 | +- define how multiple VMs, acting as an appliance, may communicate |
| 81 | + |
| 82 | +These issues are all addressed by the related Open Virtual Appliance specification. |
| 83 | + |
| 84 | +An XVA is a directory containing, at a minimum, a file called `ova.xml`. This file describes the VM contained within the XVA and is described in Section 3.2. Disks are stored within sub-directories and are referenced from the ova.xml. The format of disk data is described later in Section 3.3. |
| 85 | + |
| 86 | +The following terms will be used in the rest of the chapter: |
| 87 | + |
| 88 | +- HVM: a mode in which unmodified OS kernels run with the help of virtualization support in the hardware. |
| 89 | + |
| 90 | +- PV: a mode in which specially modified "paravirtualized" kernels run explicitly on top of a hypervisor without requiring hardware support for virtualization. |
| 91 | + |
| 92 | +The "ova.xml" file contains the following elements: |
| 93 | + |
| 94 | +```xml |
| 95 | +<appliance version="0.1"> |
| 96 | +``` |
| 97 | + |
| 98 | +The number in the attribute "version" indicates the version of this specification to which the XVA is constructed; in this case version 0.1. Inside the \<appliance\> there is exactly one \<vm\>: (in the OVA specification, multiple \<vm\>s are permitted) |
| 99 | + |
| 100 | +```xml |
| 101 | +<vm name="name"> |
| 102 | +``` |
| 103 | + |
| 104 | +Each `<vm>` element describes one VM. The "name" attribute is for future internal use only and must be unique within the ova.xml file. The "name" attribute is permitted to be any valid UTF-8 string. Inside each \<vm\> tag are the following compulsory elements: |
| 105 | + |
| 106 | +```xml |
| 107 | +<label>... text ... </label> |
| 108 | +``` |
| 109 | + |
| 110 | +A short name for the VM to be displayed in a UI. |
| 111 | + |
| 112 | +```xml |
| 113 | +<shortdesc> ... description ... </shortdesc> |
| 114 | +``` |
| 115 | + |
| 116 | +A description for the VM to be displayed in the UI. Note that for both `<label>` and `<shortdesc>` contents, leading and trailing whitespace will be ignored. |
| 117 | + |
| 118 | +```xml |
| 119 | +<config mem_set="268435456" vcpus="1"/> |
| 120 | +``` |
| 121 | + |
| 122 | +The `<config>` element has attributes which describe the amount of memory in bytes (`mem_set`) and number of CPUs (VCPUs) the VM should have. |
| 123 | + |
| 124 | +Each `<vm>` has zero or more `<vbd>` elements representing block devices which look like the following: |
| 125 | + |
| 126 | +```xml |
| 127 | +<vbd device="sda" function="root" mode="w" vdi="vdi_sda"/> |
| 128 | +``` |
| 129 | + |
| 130 | +The attributes have the following meanings: |
| 131 | + |
| 132 | +* `device`: name of the physical device to expose to the VM. For linux guests |
| 133 | + we use "sd[a-z]" and for windows guests we use "hd[a-d]". |
| 134 | +* `function`: if marked as "root", this disk will be used to boot the guest. |
| 135 | + (NB this does not imply the existence of the Linux root i.e. / filesystem) |
| 136 | + Only one device should be marked as "root". See Section 3.4 describing VM |
| 137 | + booting. Any other string is ignored. |
| 138 | +* `mode`: either "w" or "ro" if the device is to be read/write or read-only |
| 139 | +* `vdi`: the name of the disk image (represented by a `<vdi>` element) to which |
| 140 | + this block device is connected |
| 141 | + |
| 142 | +Each `<vm>` may have an optional `<hacks>` section like the following: |
| 143 | + |
| 144 | +```xml |
| 145 | +<hacks is_hvm="false" kernel_boot_cmdline="root=/dev/sda1 ro"/> |
| 146 | +``` |
| 147 | + |
| 148 | +The `<hacks>` element will be removed in future. The attribute `is_hvm` is |
| 149 | +either `true` or `false`, depending on whether the VM should be booted in HVM or not. |
| 150 | +The `kernel_boot_cmdline` contains additional kernel commandline arguments when |
| 151 | +booting a guest using pygrub. |
| 152 | + |
| 153 | +In addition to a `<vm>` element, the `<appliance>` will contain zero or more |
| 154 | +`<vdi>` elements like the following: |
| 155 | + |
| 156 | +```xml |
| 157 | +<vdi name="vdi_sda" size="5368709120" source="file://sda" type="dir-gzipped-chunks"> |
| 158 | +``` |
| 159 | + |
| 160 | +Each `<vdi>` corresponds to a disk image. The attributes have the following meanings: |
| 161 | + |
| 162 | +* `name`: name of the VDI, referenced by the vdi attribute of `<vbd>`elements. |
| 163 | + Any valid UTF-8 string is permitted. |
| 164 | +* `size`: size of the required image in bytes |
| 165 | +* `source`: a URI describing where to find the data for the image, only |
| 166 | + file:// URIs are currently permitted and must describe paths relative to the |
| 167 | + directory containing the ova.xml |
| 168 | +* `type`: describes the format of the disk data |
| 169 | + |
| 170 | +A single disk image encoding is specified in which has type "dir-gzipped-chunks": Each image is represented by a directory containing a sequence of files as follows: |
| 171 | + |
| 172 | +```sh |
| 173 | +-rw-r--r-- 1 dscott xendev 458286013 Sep 18 09:51 chunk000000000.gz |
| 174 | +-rw-r--r-- 1 dscott xendev 422271283 Sep 18 09:52 chunk000000001.gz |
| 175 | +-rw-r--r-- 1 dscott xendev 395914244 Sep 18 09:53 chunk000000002.gz |
| 176 | +-rw-r--r-- 1 dscott xendev 9452401 Sep 18 09:53 chunk000000003.gz |
| 177 | +-rw-r--r-- 1 dscott xendev 1096066 Sep 18 09:53 chunk000000004.gz |
| 178 | +-rw-r--r-- 1 dscott xendev 971976 Sep 18 09:53 chunk000000005.gz |
| 179 | +-rw-r--r-- 1 dscott xendev 971976 Sep 18 09:53 chunk000000006.gz |
| 180 | +-rw-r--r-- 1 dscott xendev 971976 Sep 18 09:53 chunk000000007.gz |
| 181 | +-rw-r--r-- 1 dscott xendev 573930 Sep 18 09:53 chunk000000008.gz |
| 182 | +``` |
| 183 | + |
| 184 | +Each file (named "chunk-XXXXXXXXX.gz") is a gzipped file containing exactly 1e9 bytes (1GB, not 1GiB) of raw block data. The small size was chosen to be safely under the maximum file size limits of several filesystems. If the files are gunzipped and then concatenated together, the original image is recovered. |
| 185 | + |
| 186 | +Because the import and export of VMs can take some time to complete, an |
| 187 | +asynchronous HTTP interface to the import and export operations is |
| 188 | +provided. To perform an export using the XenServer API, construct |
| 189 | +an HTTP GET call providing a valid session ID, task ID and VM UUID, as |
| 190 | +shown in the following pseudo code: |
| 191 | + |
| 192 | + task = Task.create() |
| 193 | + result = HTTP.get( |
| 194 | + server, 80, "/export?session_id=&task_id=&ref="); |
| 195 | + |
| 196 | +For the import operation, use an HTTP PUT call as demonstrated in the |
| 197 | +following pseudo code: |
| 198 | + |
| 199 | + task = Task.create() |
| 200 | + result = HTTP.put( |
| 201 | + server, 80, "/import?session_id=&task_id=&ref="); |
0 commit comments