You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -7,91 +7,63 @@ VMs can be exported to a file and later imported to any XenServer host. The expo
7
7
8
8
The following arguments are passed on the command line:
9
9
10
-
<table>
11
-
<colwidth="28%" />
12
-
<colwidth="68%" />
13
-
<thead>
14
-
<trclass="header">
15
-
<thalign="left">Argument</th>
16
-
<thalign="left">Description</th>
17
-
</tr>
18
-
</thead>
19
-
<tbody>
20
-
<trclass="odd">
21
-
<tdalign="left">session_id</td>
22
-
<tdalign="left">the reference of the session being used to authenticate; required only when not using HTTP basic authentication</td>
23
-
</tr>
24
-
<trclass="even">
25
-
<tdalign="left">task_id</td>
26
-
<tdalign="left">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</td>
27
-
</tr>
28
-
<trclass="odd">
29
-
<tdalign="left">ref</td>
30
-
<tdalign="left">the reference of the VM; required only if not using the UUID</td>
31
-
</tr>
32
-
<trclass="even">
33
-
<tdalign="left">uuid</td>
34
-
<tdalign="left">the UUID of the VM; required only if not using the reference</td>
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
+
38
17
39
18
For example, using the Linux command line tool cURL:
will export the specified VM to the file `exportfile`.
44
25
45
26
To export just the metadata, use the URI `http://server/export_metadata`.
46
27
47
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:
48
29
49
-
<table>
50
-
<colwidth="28%" />
51
-
<colwidth="68%" />
52
-
<thead>
53
-
<trclass="header">
54
-
<thalign="left">Argument</th>
55
-
<thalign="left">Description</th>
56
-
</tr>
57
-
</thead>
58
-
<tbody>
59
-
<trclass="odd">
60
-
<tdalign="left">restore</td>
61
-
<tdalign="left">if <em>true</em>, 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.</td>
62
-
</tr>
63
-
<trclass="even">
64
-
<tdalign="left">force</td>
65
-
<tdalign="left">if <em>true</em>, any checksum failures will be ignored (the default is to destroy the VM if a checksum error is detected)</td>
66
-
</tr>
67
-
<trclass="odd">
68
-
<tdalign="left">sr_id</td>
69
-
<tdalign="left">the reference of an SR into which the VM should be imported. The default behavior is to import into the <em>Pool.default_SR</em>.</td>
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`
XenServer supports a human-readable legacy VM input format called XVA. This section describes the syntax and structure of XVA.
66
+
Xapi supports a human-readable legacy VM input format called XVA. This section describes the syntax and structure of XVA.
95
67
96
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.
97
69
@@ -119,63 +91,85 @@ The following terms will be used in the rest of the chapter:
119
91
120
92
The "ova.xml" file contains the following elements:
121
93
94
+
```xml
122
95
<applianceversion="0.1">
96
+
```
123
97
124
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)
125
99
100
+
```xml
126
101
<vmname="name">
102
+
```
127
103
128
-
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:
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:
129
105
106
+
```xml
130
107
<label>... text ... </label>
108
+
```
131
109
132
110
A short name for the VM to be displayed in a UI.
133
111
112
+
```xml
134
113
<shortdesc> ... description ... </shortdesc>
114
+
```
135
115
136
-
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.
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.
137
117
118
+
```xml
138
119
<configmem_set="268435456"vcpus="1"/>
120
+
```
139
121
140
-
The `<config>` element has attributes which describe the amount of memory in bytes (mem\_set) and number of CPUs (VCPUs) the VM should have.
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.
141
123
142
-
Each `<vm>` has zero or more \<vbd\> elements representing block devices which look like the following:
124
+
Each `<vm>` has zero or more `<vbd>` elements representing block devices which look like the following:
name of the physical device to expose to the VM. For linux guests we use "sd[a-z]" and for windows guests we use "hd[a-d]".
150
-
151
-
function
152
-
if marked as "root", this disk will be used to boot the guest. (NB this does not imply the existence of the Linux root i.e. / filesystem) Only one device should be marked as "root". See Section 3.4 describing VM booting. Any other string is ignored.
153
-
154
-
mode
155
-
either "w" or "ro" if the device is to be read/write or read-only
156
-
157
-
vdi
158
-
the name of the disk image (represented by a \<vdi\> element) to which this block device is connected
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
159
141
160
-
Each \<vm\> may have an optional \<hacks\> section like the following:\<hacks is\_hvm="false" kernel\_boot\_cmdline="root=/dev/sda1 ro"/\> The \<hacks\> element is present in the XVA files generated by XenServer but will be removed in future. The attribute "is\_hvm" is either "true" or "false", depending on whether the VM should be booted in HVM or not. The "kernel\_boot\_cmdline" contains additional kernel commandline arguments when booting a guest using pygrub.
142
+
Each `<vm>` may have an optional `<hacks>` section like the following:
161
143
162
-
In addition to a \<vm\> element, the \<appliance\> will contain zero or more \<vdi\> elements like the following:
Each `<vdi>` corresponds to a disk image. The attributes have the following meanings:
172
161
173
-
- source: a URI describing where to find the data for the image, only file:// URIs are currently permitted and must describe paths relative to the directory containing the ova.xml
174
-
175
-
- type: describes the format of the disk data (see Section 3.3)
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
176
169
177
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:
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.
190
185
191
-
XenServer provides two mechanisms for booting a VM: (i) using a paravirtualized kernel extracted through pygrub; and (ii) using HVM. The current implementation uses the "is\_hvm" flag within the \<hacks\> section to decide which mechanism to use.
192
-
193
-
This rest of this section describes a very simple Debian VM packaged as an XVA. The VM has two disks, one with size 5120MiB and used for the root filesystem and used to boot the guest using pygrub and the other of size 512MiB which is used for swap. The VM has 512MiB of memory and uses one virtual CPU.
194
-
195
-
At the topmost level the simple Debian VM is represented by a single directory:
196
-
197
-
$ ls -l
198
-
total 4
199
-
drwxr-xr-x 3 dscott xendev 4096 Oct 24 09:42 very simple Debian VM
200
-
201
-
Inside the main XVA directory are two sub-directories - one per disk - and the single file: ova.xml:
202
-
203
-
$ ls -l very\ simple\ Debian\ VM/
204
-
total 8
205
-
-rw-r--r-- 1 dscott xendev 1016 Oct 24 09:42 ova.xml
206
-
drwxr-xr-x 2 dscott xendev 4096 Oct 24 09:42 sda
207
-
drwxr-xr-x 2 dscott xendev 4096 Oct 24 09:53 sdb
208
-
209
-
Inside each disk sub-directory are a set of files, each file contains 1GB of raw disk block data compressed using gzip:
210
-
211
-
$ ls -l very\ simple\ Debian\ VM/sda/
212
-
total 2053480
213
-
-rw-r--r-- 1 dscott xendev 202121645 Oct 24 09:43 chunk-000000000.gz
214
-
-rw-r--r-- 1 dscott xendev 332739042 Oct 24 09:45 chunk-000000001.gz
215
-
-rw-r--r-- 1 dscott xendev 401299288 Oct 24 09:48 chunk-000000002.gz
216
-
-rw-r--r-- 1 dscott xendev 389585534 Oct 24 09:50 chunk-000000003.gz
217
-
-rw-r--r-- 1 dscott xendev 624567877 Oct 24 09:53 chunk-000000004.gz
218
-
-rw-r--r-- 1 dscott xendev 150351797 Oct 24 09:54 chunk-000000005.gz
219
-
220
-
$ ls -l very\ simple\ Debian\ VM/sdb
221
-
total 516
222
-
-rw-r--r-- 1 dscott xendev 521937 Oct 24 09:54 chunk-000000000.gz
223
-
224
-
The example simple Debian VM would have an XVA file like the following:
0 commit comments