1
2 Document Number: DSP0243
3 Date: 2008-09-04
4 Version: 1.0.0d
5 Open Virtualization Format Specification
6 Document Type: Specification
7 Document Status: Preliminary Standard
8 Document Language: E
Open Virtualization Format Specification DSP0243
9 Copyright notice
10 Copyright © 2008 Distributed Management Task Force, Inc. (DMTF). All rights reserved.
11 DMTF is a not-for-profit association of industry members dedicated to promoting enterprise and systems 12 management and interoperability. Members and non-members may reproduce DMTF specifications and 13 documents for uses consistent with this purpose, provided that correct attribution is given. As DMTF 14 specifications may be revised from time to time, the particular version and release date should always be 15 noted.
16 Implementation of certain elements of this standard or proposed standard may be subject to third party 17 patent rights, including provisional patent rights (herein "patent rights"). DMTF makes no representations 18 to users of the standard as to the existence of such rights, and is not responsible to recognize, disclose, 19 or identify any or all such third party patent right, owners or claimants, nor for any incomplete or 20 inaccurate identification or disclosure of such rights, owners or claimants. DMTF shall have no liability to 21 any party, in any manner or circumstance, under any legal theory whatsoever, for failure to recognize, 22 disclose, or identify any such third party patent rights, or for such party’s reliance on the standard or 23 incorporation thereof in its product, protocols or testing procedures. DMTF shall have no liability to any 24 party implementing such standard, whether such implementation is foreseeable or not, nor to any patent 25 owner or claimant, and shall have no liability or responsibility for costs or losses incurred if a standard is 26 withdrawn or modified after publication, and shall be indemnified and held harmless by any party 27 implementing the standard from any and all claims of infringement by a patent owner for such 28 implementations.
2 Version 1.0.0d DSP0243 Open Virtualization Format Specification
29 CONTENTS
30 Foreword ...... 5 31 Introduction ...... 6 32 1 Scope ...... 7 33 2 Normative References...... 7 34 2.1 Approved References ...... 7 35 2.2 Other References...... 8 36 3 Terms and Definitions ...... 8 37 4 Symbols and Abbreviated Terms ...... 10 38 5 OVF Packages ...... 10 39 5.1 OVF Package Structure...... 10 40 5.2 Virtual Disk Formats...... 12 41 5.3 Distribution as a Single File ...... 12 42 5.4 Distribution as a Set of Files ...... 13 43 6 OVF Descriptor...... 13 44 7 Envelope element ...... 13 45 7.1 File References...... 15 46 7.2 Content Part...... 16 47 7.3 Extensibility ...... 16 48 7.4 Compatibility ...... 17 49 8 Virtual Hardware Description...... 17 50 8.1 VirtualHardware Section ...... 17 51 8.2 Extensibility ...... 18 52 8.3 Virtual Hardware Elements ...... 19 53 8.4 Ranges on Elements...... 21 54 9 Core Metadata Sections...... 23 55 9.1 DiskSection ...... 24 56 9.2 NetworkSection...... 25 57 9.3 ResourceAllocationSection...... 25 58 9.4 AnnotationSection...... 26 59 9.5 ProductSection...... 26 60 9.6 EulaSection...... 29 61 9.7 StartupSection ...... 29 62 9.8 DeploymentOptionSection ...... 30 63 9.9 OperatingSystemSection ...... 32 64 9.10 InstallSection...... 33 65 10 Internationalization ...... 33 66 11 OVF Environment...... 35 67 11.1 Environment Document ...... 35 68 11.2 Transport...... 36 69 ANNEX A (informative) Symbols and Conventions ...... 37 70 ANNEX B (informative) Change Log...... 38 71 ANNEX C (normative) OVF XSD ...... 39 72
Version 1.0.0d 3 Open Virtualization Format Specification DSP0243
73 Tables
74 Table 1 – XML Namespace Prefixes ...... 13 75 Table 2 – Actions for Child Elements with ovf:required Attribute...... 19 76 Table 3 – HostResource Element ...... 20 77 Table 4 – Elements for Virtual Devices and Controllers ...... 21 78 Table 5 – Property types...... 28 79 Table 6 – Property qualifiers ...... 29 80
4 Version 1.0.0d DSP0243 Open Virtualization Format Specification
81 Foreword
82 The Open Virtualization Format Specification (DSP0243) was prepared by the DMTF System 83 Virtualization, Partitioning, and Clustering Working Group.
84 This specification has been developed as a result of joint work with many individuals and teams, 85 including: 86 • Simon Crosby, XenSource 87 • Ron Doyle, IBM 88 • Michael Gionfriddo, Sun Microsystems 89 • Steffen Grarup, VMware (Co-Editor) 90 • Steve Hand, Symantec 91 • Mark Hapner, Sun Microsystems 92 • Daniel Hiltgen, VMware 93 • Michael Johanssen, IBM 94 • Lawrence J. Lamers, VMware (Chair) 95 • Fumio Machida, NEC Corporation 96 • Andreas Maier, IBM 97 • Ewan Mellor, XenSource 98 • John Parchem, Microsoft 99 • Shishir Pardikar, XenSource 100 • Stephen J. Schmidt, IBM 101 • René W. Schmidt, VMware (Co-Editor) 102 • Andrew Warfield, XenSource 103 • Mark D. Weitzel, IBM 104 • John Wilson, Dell
Version 1.0.0d 5 Open Virtualization Format Specification DSP0243
105 Introduction
106 The Open Virtualization Format (OVF) Specification describes an open, secure, portable, efficient and 107 extensible format for the packaging and distribution of software to be run in virtual machines. The key 108 properties of the format are as follows: 109 • Optimized for distribution 110 OVF supports content verification and integrity checking based on industry-standard public key 111 infrastructure, and it provides a basic scheme for management of software licensing. 112 • Optimized for a simple, automated user experience 113 OVF supports validation of the entire package and each virtual machine or metadata 114 component of the OVF during the installation phases of the virtual machine (VM) lifecycle 115 management process. It also packages with the package relevant user-readable descriptive 116 information that a virtualization platform can use to streamline the installation experience. 117 • Supports both single VM and multiple-VM configurations 118 OVF supports both standard single VM packages and packages containing complex, multi-tier 119 services consisting of multiple interdependent VMs. 120 • Portable VM packaging 121 OVF is virtualization platform neutral, while also enabling platform-specific enhancements to be 122 captured. It supports the full range of virtual hard disk formats used for hypervisors today, and it 123 is extensible, which will allow it to accommodate formats that may arise in the future. Virtual 124 machine properties are captured concisely and accurately. 125 • Vendor and platform independent 126 OVF does not rely on the use of a specific host platform, virtualization platform, or guest 127 operating system. 128 • Extensible 129 OVF is immediately useful — and extensible. It is designed to be extended as the industry 130 moves forward with virtual appliance technology. It also supports and permits the encoding of 131 vendor-specific metadata to support specific vertical markets. 132 • Localizable 133 OVF supports user-visible descriptions in multiple locales, and it supports localization of the 134 interactive processes during installation of an appliance. This capability allows a single 135 packaged appliance to serve multiple market opportunities. 136 • Open standard 137 OVF has arisen from the collaboration of key vendors in the industry, and it is developed in an 138 accepted industry forum as a future standard for portable virtual machines.
139 It is not an explicit goal for OVF to be an efficient execution format. A hypervisor is allowed but not 140 required to run software in virtual machines directly out of the Open Virtualization Format.
141
6 Version 1.0.0d DSP0243 Open Virtualization Format Specification
142 Open Virtualization Format Specification
143 1 Scope
144 The Open Virtualization Format (OVF) Specification describes an open, secure, portable, efficient and 145 extensible format for the packaging and distribution of software to be run in virtual machines.
146 2 Normative References
147 The following referenced documents are indispensable for the application of this document. For dated 148 references, only the edition cited applies. For undated references, the latest edition of the referenced 149 document (including any amendments) applies.
150 2.1 Approved References
151 ANSI/IEEE Standard 1003.1-2001, IEEE Standard for Information Technology- Portable Operating 152 System Interface (POSIX), Institute of Electrical and Electronics Engineers, August 2001, 153 http://ieeexplore.ieee.org/xpl/tocresult.jsp?isNumber=1316
154 DMTF DSP0004, Common Information Model (CIM) Infrastructure Specification, 155 http://www.dmtf.org/standards/published_documents/DSP0004.pdf
156 DMTF DSP1043, Allocation Capabilities Profile (ACP), 157 http://www.dmtf.org/standards/published_documents/DSP1043.pdf
158 DMTF CIM Schema Version 2.19 (MOF files), 159 http://www.dmtf.org/standards/cim/cim_schema_v219
160 DMTF DSP1041, Resource Allocation Profile (RAP), 161 http://www.dmtf.org/standards/published_documents/DSP1041.pdf
162 DMTF DSP1042, System Virtualization Profile (SVP), 163 http://www.dmtf.org/standards/published_documents/DSP1042.pdf
164 DMTF DSP1057, Virtual System Profile (VSP), 165 http://www.dmtf.org/standards/published_documents/DSP1057.pdf
166 DMTF DSP0230, WS-CIM Mapping Specification, 167 http://www.dmtf.org/standards/published_documents/DSP0230.pdf
168 IETF RFC 1738, T. Berners-Lee, Uniform Resource Locators (URL), December 1994, 169 http://www.ietf.org/rfc/rfc1738.txt
170 IETF RFC1952, P. Deutsch, GZIP file format specification version 4.3, May 1996, 171 http://www.ietf.org/rfc/rfc1952.txt
172 IETF RFC 2234, Augmented BNF (ABNF), 173 http://www.ietf.org/rfc/rfc2234.txt
174 IETF RFC 2616, R. Fielding et al, Hypertext Transfer Protocol – HTTP/1.1, June 1999, 175 http://www.ietf.org/rfc/rfc2616.txt
176 IETF RFC 2818, E. Rescorla, HTTP over TLS, May 2000, 177 http://www.ietf.org/rfc/rfc2818.txt
Version 1.0.0d 7 Open Virtualization Format Specification DSP0243
178 IEFT RFC 3986, Uniform Resource Identifiers (URI): Generic Syntax, 179 http://www.ietf.org/rfc/rfc3986.txt
180 ISO 9660, 1988 Information processing-Volume and file structure of CD-ROM for information interchange, 181 http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=17505
182 2.2 Other References
183 ISO, ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards, 184 http://isotc.iso.org/livelink/livelink.exe?func=ll&objId=4230456&objAction=browse&sort=subtype
185 W3C, Y. Savourel et al, Best Practices for XML Internationalization, Working Draft, October 2007, 186 http://www.w3.org/TR/2007/WD-xml-i18n-bp-20071031
187 W3C, S. Gao et al, XML Schema Definition Language (XSDL) 1.1, Part 1: Structures, Working Draft, 188 August 2007, http://www.w3.org/TR/xmlschema11-1
189 W3C, D. Peterson et al, XML Schema Definition Language (XSDL) 1.1, Part 2: Datatypes, Working Draft, 190 February 2006, http://www.w3.org/TR/xmlschema11-2
191 3 Terms and Definitions
192 For the purposes of this document, the following terms and definitions apply.
193 3.1 194 can 195 used for statements of possibility and capability, whether material, physical, or causal
196 3.2 197 cannot 198 used for statements of possibility and capability, whether material, physical, or causal
199 3.3 200 conditional 201 indicates requirements to be followed strictly to conform to the document when the specified conditions 202 are met
203 3.4 204 mandatory 205 indicates requirements to be followed strictly to conform to the document and from which no deviation is 206 permitted
207 3.5 208 may 209 indicates a course of action permissible within the limits of the document
210 3.6 211 need not 212 indicates a course of action permissible within the limits of the document
213 3.7 214 optional 215 indicates a course of action permissible within the limits of the document
8 Version 1.0.0d DSP0243 Open Virtualization Format Specification
216 3.8 217 shall 218 indicates requirements to be followed strictly to conform to the document and from which no deviation is 219 permitted
220 3.9 221 shall not 222 indicates requirements to be followed strictly to conform to the document and from which no deviation is 223 permitted
224 3.10 225 should 226 indicates that among several possibilities, one is recommended as particularly suitable, without 227 mentioning or excluding others, or that a certain course of action is preferred but not necessarily required
228 3.11 229 should not 230 indicates that a certain possibility or course of action is deprecated but not prohibited
231 3.12 232 appliance 233 see virtual appliance
234 3.13 235 deployment platform 236 the product that installs an OVF package
237 3.14 238 guest software 239 the software, stored on the virtual disks, that runs when a virtual machine is powered on 240 The guest is typically an operating system and some user-level applications and services.
241 3.15 242 OVF package 243 OVF XML descriptor file accompanied by zero or more files
244 3.16 245 platform 246 see deployment platform
247 3.17 248 virtual appliance 249 a service delivered as a complete software stack installed on one or more virtual machines 250 A virtual appliance is typically expected to be delivered in an OVF package.
251 3.18 252 virtual hardware 253 the hardware (including the CPU, controllers, Ethernet devices, and disks) that is seen by the guest 254 software
Version 1.0.0d 9 Open Virtualization Format Specification DSP0243
255 3.19 256 virtual machine 257 the complete environment that supports the execution of guest software 258 A virtual machine is a full encapsulation of the virtual hardware, virtual disks, and the metadata 259 associated with it. Virtual machines allow multiplexing of the underlying physical machine through a 260 software layer called a hypervisor.
261 3.20 262 virtual machine collection 263 a service comprised of a set of virtual machines 264 The service can be a simple set of one or more virtual machines, or it can be a complex service built out 265 of a combination of virtual machines and other virtual machine collections. Because virtual machine 266 collections can be composed, it enables complex nested components.
267 4 Symbols and Abbreviated Terms
268 The following symbols and abbreviations are used in this document.
269 4.1 270 CIM 271 Common Information Model
272 4.2 273 IP 274 Internet Protocol
275 4.3 276 OVF 277 Open Virtualization Format
278 4.4 279 VM 280 Virtual Machine
281 5 OVF Packages
282 5.1 OVF Package Structure
283 An OVF package shall consist of the following files: 284 • one OVF descriptor file (descriptor file or .ovf file) 285 • zero or one OVF manifest file (manifest file or .mf file) 286 • zero or one OVF certification file (certification file or .cert file) 287 • zero or more disk image files 288 • zero or more additional resource files, such as ISO images
289 The file extensions .ovf, .mf and .cert should be used. 290 EXAMPLE 1: The following list of files is an example of an OVF package. 291 package.ovf 292 package.mf 293 de-DE-resources.xml
10 Version 1.0.0d DSP0243 Open Virtualization Format Specification
294 vmdisk1.vmdk 295 vmdisk2.vmdk 296 resource.iso 297 NOTE: The previous example uses VMDK disk files, but multiple disk formats are supported.
298 Optionally, an OVF package may have a manifest file with extension .mf containing the SHA-1 digests of 299 individual files in the package. The manifest file shall have the same base name as the .ovf file. If the 300 manifest file is present, a consumer of the OVF package shall verify the digests by computing the actual 301 SHA-1 digests and comparing them with the digests listed in the manifest file.
302 The syntax definitions below use ABNF with the exceptions listed in ANNEX A.
303 The format of the .mf file is as follows: 304 manifest_file = *( file_digest ) 305 file_digest = algorithm "(" file_name ")" "=" digest nl 306 algorithm = "SHA1" 307 digest = 40( hex-digit ) // 160-bit digest in 40-digit hexadecimal 308 hex-digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "a" | 309 "b" | "c" | "d" | "e" | "f" 310 nl = 0x0a 311 EXAMPLE 2: The following example show the partial contents of a manifest file. 312 SHA1(package.ovf)= 237de026fb285b85528901da058475e56034da95 313 SHA1(vmdisk1.vmdk)= 393a66df214e192ffbfedb78528b5be75cc9e1c3
314 An OVF package may be signed by signing the manifest file. The signature of the digest is stored in a 315 .cert file along with the base64-encoded X.509 certificate. The .cert file shall have the same base name 316 as the OVF descriptor file. A consumer of the OVF package shall verify the signature and should validate 317 the certificate. The format of the .cert file shall be: 318 certificate_file = signature_part certificate_part 319 signature_part = algorithm "(" file_name ")" "=" signature nl 320 algorithm = "SHA1" 321 signature = 128( hex-digit) // 512-bit signature in 128 digit hexadecimal 322 certificate_part = certificate_header certificate_body certificate_footer 323 certificate_header = "-----BEGIN CERTIFICATE-----" nl 324 certificate_footer = "-----END CERTIFICATE-----" nl 325 certificate_body = base64-encoded-certificate nl 326 // base64-encoded-certificate is a base64-encoded X.509 327 // certificate, which may be split across multiple lines 328 hex-digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "a" 329 | "b" | "c" | "d" | "e" | "f" 330 nl = 0x0a 331 EXAMPLE 3: The following list of files is an example of a signed OVF package. 332 package.ovf 333 package.mf 334 package.cert 335 de-DE-resources.xml 336 vmdisk1.vmdk 337 vmdisk2.vmdk 338 resource.iso
Version 1.0.0d 11 Open Virtualization Format Specification DSP0243
339 EXAMPLE 4: The following example shows the contents of a sample OVF certification file: 340 SHA1(package.mf)= 7f4b8efb8fe20c06df1db68281a63f1b088e19dbf00e5af9db5e8e3e319de 341 7019db88a3bc699bab6ccd9e09171e21e88ee20b5255cec3fc28350613b2c529089 342 -----BEGIN CERTIFICATE----- 343 MIIBgjCCASwCAQQwDQYJKoZIhvcNAQEEBQAwODELMAkGA1UEBhMCQVUxDDAKBgNV 344 BAgTA1FMRDEbMBkGA1UEAxMSU1NMZWF5L3JzYSB0ZXN0IENBMB4XDTk1MTAwOTIz 345 MzIwNVoXDTk4MDcwNTIzMzIwNVowYDELMAkGA1UEBhMCQVUxDDAKBgNVBAgTA1FM 346 RDEZMBcGA1UEChMQTWluY29tIFB0eS4gTHRkLjELMAkGA1UECxMCQ1MxGzAZBgNV 347 BAMTElNTTGVheSBkZW1vIHNlcnZlcjBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQC3 348 LCXcScWua0PFLkHBLm2VejqpA1F4RQ8q0VjRiPafjx/Z/aWH3ipdMVvuJGa/wFXb 349 /nDFLDlfWp+oCPwhBtVPAgMBAAEwDQYJKoZIhvcNAQEEBQADQQArNFsihWIjBzb0 350 DCsU0BvL2bvSwJrPEqFlkDq3F4M6EGutL9axEcANWgbbEdAvNJD1dmEmoWny27Pn 351 IMs6ZOZB 352 -----END CERTIFICATE-----
353 5.2 Virtual Disk Formats
354 OVF does not require any specific disk format to be used, but to comply with this specification the disk 355 format shall be given by a URI which identifies an unencumbered specification on how to interpret the 356 disk format. The specification need not be machine readable, but it shall be static and unique so that the 357 URI may be used as a key by software reading an OVF package to uniquely determine the format of the 358 disk. The specification shall provide sufficient information so that a skilled person can properly interpret 359 the disk format for both reading and writing of disk data. It is recommended that these URIs are 360 resolvable.
361 5.3 Distribution as a Single File
362 An OVF package can be stored as a single file using the TAR format. The extension of that file should be 363 .ova (open virtual appliance or application). 364 EXAMPLE: The following example shows a sample filename for an OVF package of this type: 365 D:\virtualappliances\myapp.ova
366 Ordinarily, a TAR extraction tool would have to scan the whole archive, even if the file requested is found 367 at the beginning, because replacement files can be appended without modifying the rest of the archive. 368 For OVF TAR files, duplication is not allowed within the archive. In addition, the files shall be in the 369 following order inside the archive: 370 1) .ovf descriptor file 371 2) .mf manifest file (optional) 372 3) .cert certificate file (optional) 373 4) The remaining files shall be in the same order as listed in the References section (see 7.1). 374 Note that any external string resource bundle files for internationalization shall be first in the 375 References section (see clause 10). 376 5) .mf manifest file (optional) 377 6) .cert certificate (optional)
378 Note that the certificate file is optional. If no certificate file is present, the manifest file is also optional. If 379 the manifest or certificate files are present, they shall either both be placed after the OVF descriptor file, 380 or both be placed at the end of the archive.
12 Version 1.0.0d DSP0243 Open Virtualization Format Specification
381 For deployment, the ordering restriction ensures that it is possible to extract the OVF descriptor from an 382 OVF TAR file without scanning the entire archive. For generation, the ordering restriction ensures that an 383 OVF TAR file can easily be generated on-the-fly. The restrictions do not prevent OVF TAR files from 384 being created using standard TAR packaging tools.
385 The TAR format used shall comply with the USTAR (Uniform Standard Tape Archive) format as defined 386 by the POSIX IEEE 1003.1 standards group.
387 5.4 Distribution as a Set of Files
388 An OVF package can be made available as a set of files — for example on a standard Web server: 389 http://mywebsite/virtualappliances/package.ovf 390 http://mywebsite/virtualappliances/vmdisk1.vmdk 391 http://mywebsite/virtualappliances/vmdisk2.vmdk 392 http://mywebsite/virtualappliances/resource.iso 393 http://mywebsite/virtualappliances/de-DE-resources.xml
394 6 OVF Descriptor
395 All metadata about the package and its contents is stored in the OVF descriptor. This is an extensible 396 XML document for encoding information, such as product details, virtual hardware requirements, and 397 licensing.
398 The ovf-envelope.xsd XML schema definition file for the OVF descriptor contains the elements and 399 attributes.
400 Clauses 7, 8, and 9, describe the semantics, structure, and extensibility framework of the XML descriptor. 401 These clauses are not a replacement for reading the schema definitions, but they complement the 402 schema definitions.
403 The XML document of an OVF descriptor shall contain one Envelope element, which is the only element 404 allowed at the top level.
405 The XML namespaces used in this specification are listed in Table 1. The choice of any namespace prefix 406 is arbitrary and not semantically significant.
407 Table 1 – XML Namespace Prefixes
Prefix XML Namespace ovf http://schemas.dmtf.org/ovf/envelope/1 ovfenv http://schemas.dmtf.org/ovf/environment/1 rasd http://schemas.dmtf.org/wbem/wscim/1/cim- schema/2/CIM_ResourceAllocationSettingData vssd http://schemas.dmtf.org/wbem/wscim/1/cim- schema/2/CIM_VirtualSystemSettingData
408 7 Envelope element
409 The Envelope element describes all metadata for the virtual machines (including virtual hardware), as 410 well as the structure of the OVF package itself.
Version 1.0.0d 13 Open Virtualization Format Specification DSP0243
411 The outermost level of the envelope consists of the following parts: 412 • A version indication, defined by the XML namespace URIs. 413 • A list of file references to all external files that are part of the OVF package, defined by the 414 References element and its File child elements. These are typically virtual disk files, ISO 415 images, and internationalization resources. 416 • A metadata part, defined by section elements, as defined in clause 9. 417 • A description of the content, either a single virtual machine (VirtualSystem element) or a 418 collection of multiple virtual machines (VirtualSystemCollection element). 419 • A specification of message resource bundles for zero or more locales, defined by a Strings 420 element for each locale.
421 EXAMPLE: An example of the structure of an OVF descriptor with the top level Envelope element follows: 422 423
14 Version 1.0.0d DSP0243 Open Virtualization Format Specification
463 The optional xml:lang attribute on the Envelope element specifies the default locale for messages in 464 the descriptor. The optional Strings elements contain message resource bundles for different locales. 465 See clause 10 for more details on internationalization support.
466 7.1 File References
467 The file reference part defined by the References element allows a tool to easily determine the integrity 468 of an OVF package without having to parse or interpret the entire structure of the descriptor. Tools can 469 safely manipulate (for example, copy or archive) OVF packages with no risk of losing files.
470 External string resource bundle files for internationalization shall be placed first in the References 471 element, see clause 10 for details.
472 Each File element in the reference part shall be given an identifier using the ovf:id attribute. The 473 identifier shall be unique inside an OVF package. Each File element shall be specified using the 474 ovf:href attribute, which shall contain a URL. The URL schemes "file", "http", and "https" shall 475 be supported. Using other URL schemes is allowed but not recommended. If no URL scheme is 476 specified, the value of the ovf:href attribute shall be interpreted as a path name of the referenced file 477 that is relative to the location of the OVF descriptor file itself. The relative path name shall use the syntax 478 of relative-path references in IEFT RFC 3986. The referenced file shall exist. Two different File 479 elements shall not reference the same file with their ovf:href attributes.
480 The size of the referenced file can optionally be specified using the ovf:size attribute. The unit of this 481 attribute is always bytes.
482 Each file referenced by a File element may be compressed using gzip (see RFC1952), which is 483 indicated using the ovf:compression="gzip" attribute. Omitting the compression attribute, or 484 specifying it as "identity", states that no compression is used. Alternatively, if the href is an HTTP or 485 HTTPS URL, then the compression may be specified by the HTTP server by using the HTTP header 486 Content-Encoding: gzip (see RFC2616). Using HTTP content encoding in combination with the 487 ovf:compression attribute is allowed, but in general does not improve the compression ratio.
488 Files to be referenced from the reference part may be split into chunks to accommodate file size 489 restrictions on certain file systems. Chunking is indicated by the presence of the ovf:chunkSize 490 attribute; this attribute specifies the size of each chunk, except the last, which may be smaller.
491 When ovf:chunkSize is specified, the File element shall reference a chunk file representing a chunk 492 of the entire file. In this case, the value of the ovf:href attribute specifies only a part of the URL and the 493 syntax for the URL resolving to the chunk file is given below. The syntax uses ABNF with the exceptions 494 listed in ANNEX A.
495 496 chunk-url = href-value "." chunk-number 497 chunk-number = 9(decimal-digit) 498 decimal-digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
499 where href-value is the value of the ovf:href attribute, and chunk-number is the 0-based position of the 500 chunk starting with the value 0 and increases with increments of 1 for each chunk.
501 Chunking can be combined with compression, the entire file is then compressed before chunking and 502 each chunk shall be an equal slice of the compressed file, except for the last chunk which may be 503 smaller.
Version 1.0.0d 15 Open Virtualization Format Specification DSP0243
504 7.2 Content Part
505 The virtual machine configurations required by an OVF package is represented by a VirtualSystem or 506 VirtualSystemCollection element. These elements shall be given an identifier using the ovf:id 507 attribute, direct child elements of a VirtualSystemCollection shall have unique identifiers.
508 The VirtualSystem element describes a single virtual machine and is simply a container of section 509 elements. These section elements describe virtual hardware, resources, product information, and so on, 510 and are described in detail in clause 8 and 9.
511 The structure of a VirtualSystem element is as follows: 512
519 The VirtualSystemCollection element is a container of multiple VirtualSystem or 520 VirtualSystemCollection elements. Thus, arbitrary complex configurations can be described. The 521 section elements at the VirtualSystemCollection level describe appliance information, properties, 522 resource requirements, and so on, and are described in detail in clause 9.
523 The structure of a VirtualSystemCollection element is as follows: 524
535 In the OVF schema, the VirtualSystem and VirtualSystemCollection elements are part of a 536 substitution group with the Content element as head of the substitution group. The Content element is 537 abstract and cannot be used directly. Similarly, all sections are part of a substitution group with the 538 Section element as head of the substitution group. The Section element is abstract and cannot be 539 used directly.
540 All elements in the Content and Section substitution groups shall contain an Info element which 541 contains a human readable description of the meaning of this entity. See clause 10 for details on how to 542 localize the Info element.
543 7.3 Extensibility
544 The OVF schemas associated with this specification are expressed in XML Schema 1.0. Extensions that 545 are subtypes of Section can be added, but existing types cannot be extended with additional elements. 546 The plan is to add an extension model based on the design of the open content model in XML Schema 547 1.1.
16 Version 1.0.0d DSP0243 Open Virtualization Format Specification
548 Custom extensions shall not use XML namespaces defined in this specification.
549 All subtypes of Section contain an Info element which contains a human readable description of the 550 meaning of this entity. The values of Info elements can be used, for example, to give meaningful 551 warnings to users when a section is being skipped, even if the parser does not know anything about the 552 section. See clause 10 for details on how to localize the Info element.
553
554 7.4 Compatibility
555 On extensions, a Boolean ovf:required attribute specifies whether the information in the element is 556 required for correct behavior or optional. If not specified, the ovf:required attribute defaults to FALSE. 557 An OVF application that detects an extension that is required and that it does not understand shall fail.
558 For known Section elements, if additional child elements that are not understood are found and the 559 value of their ovf:required attribute is TRUE, the OVF application shall interpret the entire section as 560 one it does not understand. The check is not recursive; it applies only to the direct children of the 561 Section element.
562 This behavior ensures that older parsers will reject newer OVF specifications, unless explicitly instructed 563 not to do so. 564 EXAMPLE: 565
572
573 8 Virtual Hardware Description
574
575 8.1 VirtualHardware Section
576 The virtual hardware required by a virtual machine is specified in the VirtualHardware section. This 577 specification supports abstract or incomplete hardware descriptions in which only the major devices are 578 described. The hypervisor is allowed to create additional virtual hardware controllers and devices, as long 579 as the required devices listed in the descriptor are realized.
580 This virtual hardware description is based on the CIM classes CIM_VirtualSystemSettingData and 581 CIM_ResourceAllocationSettingData. The XML representation of the CIM model is based on the 582 WS-CIM mapping (DSP0230).
583 EXAMPLE: Example of VirtualHardware section: 584
Version 1.0.0d 17 Open Virtualization Format Specification DSP0243
588 589
599 VirtualHardware is a required child element for a VirtualSystem element, and it is disallowed as a 600 direct child element of a VirtualSystemCollection element and of an Envelope element.
601 Multiple VirtualHardware element occurrences are allowed within a single VirtualSystem element. 602 The OVF application can select the most appropriate virtual hardware description, typically based on the 603 family attribute.
604 The ovf:transport attribute specifies the types of transport mechanisms by which properties are 605 passed to the virtual machine in an OVF environment document. This attribute supports a pluggable and 606 extensible architecture for providing guest/platform communication mechanisms. Several transport types 607 can be specified separated by single space character. See 9.5 for a description of properties and clause 608 11 for a description of transport types and OVF environments.
609 The vssd:VirtualSystemType element specifies a virtual system type identifier, which is an 610 implementation defined string that uniquely identifies the type of the virtual system. For example, a virtual 611 system type identifier could be vmx-4 for VMware’s fourth-generation virtual hardware or xen-3 for Xen’s 612 third-generation virtual hardware. Zero or more virtual system type identifiers may be specified separated 613 by single space character. In order for the OVF virtual system to be deployable on a target platform, the 614 virtual machine on the target platform is required to support at least one of the virtual system types 615 identified in the vssd:VirtualSystemType elements. The virtual system type identifiers specified in 616 vssd:VirtualSystemType elements are expected to be matched against the values of property 617 VirtualSystemTypesSupported of CIM class CIM_VirtualSystemManagementCapabilities (see DSP1042).
618 The virtual hardware characteristics are described as a sequence of Item elements. The Item element 619 is an XML representation of an instance of the CIM class CIM_ResourceAllocationSettingData. 620 The element can describe all memory and CPU requirements as well as virtual hardware devices.
621 Multiple device subtypes can be specified in an Item element, separated by single space character. 622 EXAMPLE: 623
624
625 8.2 Extensibility
626 The optional ovf:required attribute on the Item element specifies whether the realization of the 627 element (for example, a CD-rom or USB controller) is required for correct behavior of the guest software. 628 If not specified, ovf:required defaults to FALSE.
629 On child elements of the Item element, the optional Boolean attribute ovf:required shall be 630 interpreted, even though these elements are in a different RASD WS-CIM namespace. A tool parsing an 631 Item element shall act according to Table 2.
18 Version 1.0.0d DSP0243 Open Virtualization Format Specification
632 Table 2 – Actions for Child Elements with ovf:required Attribute
Child Element ovf:required Attribute Value Action Known TRUE or not specified Shall interpret Item Known FALSE Shall interpret Item Unknown TRUE or not specified Shall fail Item Unknown FALSE Shall ignore Item
633 8.3 Virtual Hardware Elements
634 The general form of any Item element in a VirtualHardware element is as follows: 635
660 The elements represent the properties exposed by the CIM_ResourceAllocationSettingData 661 class. They have the semantics of defined settings as defined in DSP1041, any profiles derived from 662 DSP1041 for specific resource types, and this document. 663 EXAMPLE: The following example shows a description of the number of virtual CPUs: 664
Version 1.0.0d 19 Open Virtualization Format Specification DSP0243
673 The Description element is used to provide additional metadata about the element itself. This element 674 enables an OVF application to provide descriptive information about all items, including items that were 675 unknown at the time the application was written.
676 The Caption, Description and ElementName elements are localizable using the ovf:msgid 677 attribute from the OVF envelope namespace. See clause 10 for more details on internationalization 678 support.
679 The optional ovf:configuration attribute contains a list of configuration names. See clause 9.8 on 680 deployment options for semantics of this attribute. The optional ovf:bound attribute is used to specify 681 ranges, see clause 8.4.
682 Devices such as disks, CD-ROMs, and networks need a backing from the deployment platform. The 683 requirements on a backing are either specified using the HostResource or the Connection element.
684 For an Ethernet adapter, a logical network name is specified in the Connection element. Ethernet 685 adapters that refer to the same logical network name within an OVF package shall be deployed on the 686 same network.
687 The HostResource element is used to refer to resources included in the OVF descriptor as well as 688 logical devices on the deployment platform. Values for HostResource elements are formatted as URIs. 689 The URIs in Table 3 shall be used to refer to resources included the OVF descriptor.
690 Table 3 – HostResource Element
Content Description ovf:/file/
691 If no backing is specified for a device that requires a backing, the deployment platform shall make an 692 appropriate choice, for example, by prompting the user. Specifying more than one backing for a device is 693 not allowed.
694 Table 4 gives a brief overview on how elements are used to describe virtual devices and controllers.
20 Version 1.0.0d DSP0243 Open Virtualization Format Specification
695 Table 4 – Elements for Virtual Devices and Controllers
Element Usage rasd:Description A human-readable description of the meaning of the information. For example, “Specifies the memory size of the virtual machine”. rasd:ElementName A human-readable description of the content. For example, “256MB memory”. rasd:InstanceID A unique instance ID of the element within the section. rasd:HostResource Abstractly specifies how a device shall connect to a resource on the deployment platform. Not all devices need a backing. See Table 3. rasd:ResourceType Specifies the kind of device that is being described. rasd:OtherResourceType rasd:ResourceSubtype rasd:AutomaticAllocation For devices that are connectable, such as floppies, CD-ROMs, and Ethernet adaptors, this element specifies whether the device should be connected at power on. rasd:Parent The InstanceID of the parent controller (if any). rasd:Connection For an Ethernet adapter, this specifies the abstract network connection name for the virtual machine. All Ethernet adapters that specify the same abstract network connection name within an OVF package shall be deployed on the same network. The abstract network connection name shall be listed in the NetworkSection at the outermost envelope level. rasd:Address Device specific. For an Ethernet adapter, this specifies the MAC address. rasd:AddressOnParent For a device, this specifies its location on the controller. rasd:AllocationUnits Specifies the units of allocation used. For example, “byte * 2^20”. rasd:VirtualQuantity Specifies the quantity of resources presented. For example, “256”. rasd:Reservation Specifies the minimum quantity of resources guaranteed to be available. rasd:Limit Specifies the maximum quantity of resources that will be granted. rasd:Weight Specifies a relative priority for this allocation in relation to other allocations.
696 Only fields directly related to describing devices are mentioned. Refer to the CIM MOF for a complete 697 description of all fields.
698 8.4 Ranges on Elements
699 The optional ovf:bound attribute can be used to specify ranges for the Item elements. A range has a 700 minimum, normal, and maximum value, denoted by min, normal, and max, where min <= normal <= 701 max. The default values for min and max are those specified for normal.
702 A platform deploying an OVF package is recommended to start with the normal value and adjust the 703 value within the range for ongoing performance tuning and validation.
704 For the Item elements in VirtualHardware and ResourceAllocation elements, the following 705 additional semantics is defined: 706 • Each Item element has an optional ovf:bound attribute. This value can be specified as min, 707 max, or normal. The value defaults to normal. If the attribute is not specified or is specified as 708 normal, then the item is interpreted as being part of the regular virtual hardware or resource 709 allocation description.
Version 1.0.0d 21 Open Virtualization Format Specification DSP0243
710 • If the ovf:bound value is specified as either min or max, the item is used to specify the upper 711 or lower bound for one or more values for a given InstanceID. Such an item is called a range 712 marker.
713 The semantics of range markers are: 714 • InstanceID and ResourceType shall be specified, and the ResourceType shall match 715 other Item elements with the same InstanceID. 716 • Specifying more than one min range marker or more than one max range marker for a given 717 RASD (identified with InstanceID) is invalid. 718 • An Item element with a range marker shall have a corresponding Item element without a 719 range marker, that is, an Item element with no ovf:bound attribute or ovf:bound attribute 720 with value normal. This corresponding item specifies the default value. 721 • For an Item element where only a min range marker is specified, the max value is unbounded 722 upwards within the set of valid values for the property. 723 • For an Item where only a max range marker is specified, the min value is unbounded 724 downwards within the set of valid values for the property. 725 • The default value shall be inside the range. 726 • The use of non-integer elements in range marker RASDs is invalid. 727 EXAMPLE: The following example shows the use of range markers: 728
22 Version 1.0.0d DSP0243 Open Virtualization Format Specification
752 9 Core Metadata Sections
753 The following core metadata sections are defined:
754 Section Locations Multiplicity DiskSection Envelope Zero or One Describes meta-information about all virtual disks in the package NetworkSection Envelope Zero or One Describes logical networks used in the package ResourceAllocationSection VirtualSystemCollection Zero or One Specifies reservations, limits, and shares on a given resource, such as memory or CPU for a virtual machine collection AnnotationSection VirtualSystem Zero or One Specifies a free-form annotation on an entity VirtualSystemCollection ProductSection VirtualSystem Zero or more Specifies product-information for a package, such as VirtualSystemCollection product name and version, along with a set of properties that can be configured EulaSection VirtualSystem Zero or more Specifies a license agreement for the software in the VirtualSystemCollection package StartupSection VirtualSystemCollection Zero or One Specifies how a virtual machine collection is powered on DeploymentOptionSection Envelope Zero or One Specifies a discrete set of intended resource requirements OperatingSystemSection VirtualSystem Zero or One Specifies the installed guest operating system of a virtual machine InstallSection VirtualSystem Zero or One Specifies that the virtual machine needs to be initially booted to install and configure the software
755
756 The following clauses describe the semantics of the core sections and provide some examples. The 757 sections are used in several places of an OVF envelope, the description of each section defines where it 758 may be used. See the OVF schema for a detailed specification of all attributes and elements.
Version 1.0.0d 23 Open Virtualization Format Specification DSP0243
759 9.1 DiskSection
760 A DiskSection describes meta-information about virtual disks in the OVF package. Virtual disks and 761 their metadata are described outside the virtual hardware to facilitate sharing between virtual machines 762 within an OVF package. 763
777 DiskSection is a valid section at the outermost envelope level only.
778 Each virtual disk is represented by a Disk element that shall be given a identifier using the ovf:diskId 779 attribute, the identifier shall be unique within the DiskSection.
780 The capacity of a virtual disk shall be specified by the ovf:capacity attribute with an xs:long integer 781 value. The default unit of allocation shall be bytes. The optional string attribute 782 ovf:capacityAllocationUnits may be used to specify a particular unit of allocation. Values for 783 ovf:capacityAllocationUnits shall match the format for programmatic units defined in DSP0004.
784 The format URI (see clause 5.2) of a virtual disk shall be specified by the ovf:format attribute.
785 The ovf:fileRef attribute denotes the virtual disk content by identifying an existing File element in 786 the References element, the File element is identified by matching its ovf:id attribute value with the 787 ovf:fileRef attribute value. Omitting the ovf:fileRef attribute shall indicate an empty disk. In this 788 case, the disk shall be created and the entire disk content zeroed at installation time.
789 Different Disk elements shall not contain ovf:fileRef attributes with identical values. Disk elements 790 shall be ordered such that they identify any File elements in the same order as these are defined in the 791 References element.
792 For empty disks, rather than specifying a fixed virtual disk capacity, the capacity for an empty disk can be 793 given using an OVF property, for example ovf:capacity="${disk.size}". The OVF property shall 794 resolve to an xs:long integer value. See 9.5 for a description of OVF properties. The 795 ovf:capacityAllocationUnits attribute is useful when using OVF properties because a user may 796 be prompted and can then enter disk sizing information in e.g. gigabytes.
797 For non-empty disks, the actual used size of the disk can optionally be specified using the 798 ovf:populatedSize attribute. The unit of this attribute is always bytes. ovf:populatedSize is 799 allowed to be an estimate of used disk size but shall not be larger than ovf:capacity.
24 Version 1.0.0d DSP0243 Open Virtualization Format Specification
800 OVF allows a disk image to be represented as a set of modified blocks in comparison to a parent image. 801 The use of parent disks can often significantly reduce the size of an OVF package, if it contains multiple 802 disks with similar content. For a Disk element, a parent disk can optionally be specified using the 803 ovf:parentRef attribute, which shall contain a valid ovf:diskId reference to a different Disk 804 element. If a disk block does not exist locally, lookup for that disk block then occurs in the parent disk. In 805 DiskSection, parent Disk elements shall occur before child Disk elements that refer to them.
806 9.2 NetworkSection
807 The NetworkSection element shall list all logical networks used in the OVF package. 808
814 NetworkSection is a valid element at the outermost envelope level.
815 All networks referred to from Connection elements in all VirtualHardware elements shall be defined 816 in the NetworkSection.
817 9.3 ResourceAllocationSection
818 The ResourceAllocationSection element describes all resource allocation requirements of a 819 VirtualSystemCollection entity. These resource allocations shall be performed when deploying the 820 OVF package. 821
838 ResourceAllocationSection is a valid element for a VirtualSystemCollection entity.
839 The optional ovf:configuration attribute contains a list of configuration names. See 9.8 on 840 deployment options for semantics of this attribute.
841 The optional ovf:bound attribute contains a value of min, max, or normal. See 8.4 for semantics of this 842 attribute.
Version 1.0.0d 25 Open Virtualization Format Specification DSP0243
843 9.4 AnnotationSection
844 The AnnotationSection element is a user-defined annotation on an entity. Such annotations may be 845 displayed when deploying the OVF package. 846
850 AnnotationSection is a valid element for a VirtualSystem and a VirtualSystemCollection 851 entity.
852 See clause 10 for details on how to localize the Annotation element.
853 9.5 ProductSection
854 The ProductSection element specifies product-information for an appliance, such as product name, 855 version, vendor, and so on. 856
882 Property elements specify application-level customization parameters and are particularly relevant to 883 appliances that need to be customized during deployment with specific settings such as network identity, 884 the IP addresses of DNS servers, gateways, and others. 885 886 ProductSection is a valid section for a VirtualSystem and a VirtualSystemCollection entity.
26 Version 1.0.0d DSP0243 Open Virtualization Format Specification
887 Property elements may be grouped by using Category elements. The set of Property elements 888 grouped by a Category element is the sequence of Property elements following the Category 889 element, until but not including an element that is not a Property element. For OVF packages 890 containing a large number of Property elements, this may provide a simpler installation experience. 891 Similarly, each Property element may have a short label defined by its Label child element in addition 892 to a description defined by its Description child element. See clause 10 for details on how to localize 893 the Category element and the Description and Label child elements of the Property element.
894 Each Property element in a ProductSection shall be given an identifier that is unique within the 895 ProductSection using the ovf:key attribute.
896 Each Property element in a ProductSection shall be given a type using the ovf:type attribute and 897 optionally type qualifiers using the ovf:qualifiers attribute. Valid types are listed in Table 5 and valid 898 qualifiers are listed in Table 6.
899 The optional attribute ovf:value is used to provide a default value for a property. One or more optional 900 Value elements may be used to define alternative default values for specific configurations, as defined in 901 clause 9.8.
902 The optional attribute ovf:userConfigurable determines whether the property value is configurable 903 during the installation phase. If ovf:userConfigurable is FALSE or omitted, the ovf:value attribute 904 specifies the value to be used for that customization parameter during installation. If 905 ovf:userConfigurable is TRUE, the ovf:value attribute specifies a default value for that 906 customization parameter, which may be changed during installation.
907 A simple OVF implementation such as a command-line installer typically uses default values for 908 properties and does not prompt even though ovf:userConfigurable is set to TRUE. To force 909 prompting at startup time, omitting the ovf:value attribute is sufficient for integer and IP types, because 910 the empty string is not a valid integer or IP value. For string types, prompting can be forced by using a 911 type for a non-empty string.
912 Zero or more ProductSections can be specified within a VirtualSystem or 913 VirtualSystemCollection. Typically, a ProductSection corresponds to a particular software 914 product that is installed. Each product section at the same entity level shall have a unique ovf:class 915 and ovf:instance attribute pair. For the common case where only a single ProductSection is used, 916 the ovf:class and ovf:instance attributes are optional and default to the empty string. It is 917 recommended that the ovf:class property be used to uniquely identify the software product using the 918 reverse domain name convention. Examples of values are com.vmware.tools and 919 org.apache.tomcat. If multiple instances of the same product are installed, the ovf:instance 920 attribute is used to identify the different instances.
921 Property elements are exposed to the guest software through the OVF environment, as described in 922 clause 11. The value of the ovfenv:key attribute of a Property element exposed in the OVF 923 environment shall be constructed from the value of the ovf:key attribute of the corresponding 924 Property element defined in a ProductSection entity of an OVF descriptor as follows: 925 key-value-env = [class-value "."] key-value-prod ["." instance-value]
926 where: 927 • class-value is the value of the ovf:class attribute of the Property element defined in the 928 ProductSection entity. The production [class-value "."] shall be present if and only if 929 class-value is not the empty string. 930 • key-value-prod is the value of the ovf:key attribute of the Property element defined in the 931 ProductSection entity.
Version 1.0.0d 27 Open Virtualization Format Specification DSP0243
932 • instance-value is the value of the ovf:instance attribute of the Property element defined in 933 the ProductSection entity. The production ["." instance-value] shall be present if and only 934 if instance-value is not the empty string. 935 EXAMPLE: The following OVF environment example shows how properties can be propagated to the guest 936 software: 937
940 941 The consumer of an OVF package should prompt for properties where ovf:userConfigurable is 942 TRUE. These properties can be defined in multiple ProductSections as well as in sub-entities in the 943 OVF package.
944 The first ProductSection entity defined in the top-level Content element of a package shall define 945 summary information that describes the entire package. After installation, an OVF application could 946 choose to make this information available as an instance of the CIM_Product class.
947 Property elements specified on a VirtualSystemCollection can also be seen by its immediate 948 children (see clause 11). Children can refer to the properties of a parent VirtualSystemCollection 949 using macros on the form ${name} as value for the ovf:key attributes.
950 Table 5 lists the valid types for properties. These are a subset of CIM intrinsic types defined in DSP0004, 951 which also define the value space and format for each intrinsic type. Each Property element in a shall 952 specify a type using the ovf:type attribute.
953
954 Table 5 – Property types
Type Description uint8 Unsigned 8-bit integer sint8 Signed 8-bit integer uint16 Unsigned 16-bit integer sint16 Signed 16-bit integer uint32 Unsigned 32-bit integer sint32 Signed 32-bit integer uint64 Unsigned 64-bit integer sint64 Signed 64-bit integer string String boolean Boolean real32 IEEE 4-byte floating point real64 IEEE 8-byte floating point
955 Table 6 lists the supported CIM type qualifiers as defined in DSP0004. Each Property element in a may 956 specify type qualifiers using the ovf:qualifiers attribute.
957
28 Version 1.0.0d DSP0243 Open Virtualization Format Specification
958 Table 6 – Property qualifiers
Type Description string MinLen(min) MaxLen(max) ValueMap{...} uint8 ValueMap{...} sint8 uint16 sint16 uint32 sint32 uint64 sint64
959 The MinLen, MaxLen and ValueMap qualifiers take values as defined in DSP0004.
960 9.6 EulaSection
961 A EulaSection contains the legal terms for using its parent Content element. This license shall be 962 shown and accepted during deployment of an OVF package. Multiple EulaSections can be present in 963 an OVF. If unattended installations are allowed, all embedded license sections are implicitly accepted. 964
977 EulaSection is a valid section for a VirtualSystem and a VirtualSystemCollection entity.
978 See clause 10 for details on how to localize the License element.
979 9.7 StartupSection
980 The StartupSection specifies how a virtual machine collection is powered on and off. 981
Version 1.0.0d 29 Open Virtualization Format Specification DSP0243
989 Each Content element that is a direct child of a VirtualSystemCollection may have a 990 corresponding Item element in the StartupSection entity of the VirtualSystemCollection entity. 991 Note that Item elements can correspond to both VirtualSystem and VirtualSystemCollection 992 entities. When a start or stop action is performed on a VirtualSystemCollection entity, the 993 respective actions on the Item elements of its StartupSection entity are invoked in the specified 994 order. Whenever an Item element corresponds to a (nested) VirtualSystemCollection entity, the 995 actions on the Item elements of its StartupSection entity shall be invoked before the action on the 996 Item element corresponding to that VirtualSystemCollection entity is invoked (i.e., depth-first 997 traversal).
998 The following required attributes on Item are supported for a VirtualSystem and 999 VirtualSystemCollection: 1000 • ovf:id shall match the value of the ovf:id attribute of a Content element which is a direct 1001 child of this VirtualSystemCollection. That Content element describes the virtual 1002 machine or virtual machine collection to which the actions defined in the Item element apply. 1003 • ovf:order specifies the startup order using non-negative integer values. The order of 1004 execution of the start action is the numerical ascending order of the values. Items with same 1005 order identifier may be started up concurrently. The order of execution of the stop action is the 1006 numerical descending order of the values.
1007 The following optional attributes on Item are supported for a VirtualSystem. 1008 • ovf:startDelay specifies a delay in seconds to wait until proceeding to the next order in the 1009 start sequence. The default value is 0. 1010 • ovf:waitingForGuest enables the platform to resume the startup sequence after the guest 1011 software has reported it is ready. The interpretation of this is deployment platform specific. The 1012 default value is FALSE. 1013 • ovf:startAction specifies the start action to use. Valid values are powerOn and none. The 1014 default value is powerOn. 1015 • ovf:stopDelay specifies a delay in seconds to wait until proceeding to the previous order in 1016 the stop sequence. The default value is 0. 1017 • ovf:stopAction specifies the stop action to use. Valid values are powerOff, 1018 guestShutdown, and none. The interpretation of guestShutdown is deployment platform 1019 specific. The default value is powerOff.
1020 If not specified, an implicit default Item is created for each entity in the collection with ovf:order="0". 1021 Thus, for a trivial startup sequence no StartupSection needs to be specified.
1022 9.8 DeploymentOptionSection
1023 The DeploymentOptionSection specifies a discrete set of intended resource configurations. The 1024 author of an OVF package can include sizing metadata for different configurations. A consumer of the 1025 OVF shall select a configuration, for example, by prompting the user. The selected configuration will be 1026 visible in the OVF environment, enabling guest software to adapt to the selected configuration. See 1027 clause 11.
1028 The DeploymentOptionSection specifies an ID, label, and description for each configuration.
30 Version 1.0.0d DSP0243 Open Virtualization Format Specification
1029
1040 The DeploymentOptionSection has the following semantics: 1041 • If present, the DeploymentOptionSection is valid only at the envelope level, and only one 1042 section can be specified in an OVF descriptor. 1043 • The discrete set of configurations is described with Configuration elements, which shall 1044 have identifiers specified by the ovf:id attribute that are unique in the package. 1045 • A default Configuration element can be specified with the optional ovf:default attribute. 1046 If no default is specified, the first element in the list is the default. Specifying more than one 1047 element as the default is invalid. 1048 • The Label and Description elements are localizable using the ovf:msgid attribute. See 1049 clause 10 for more details on internationalization support.
1050 Configurations can be used to control resources for virtual hardware and for virtual machine collections. 1051 Item elements in VirtualHardwareSection elements describe resources for VirtualSystem entities, 1052 while Item elements in ResourceAllocationSection elements describe resources for virtual 1053 machine collections. For these two Item types, the following additional semantics are defined:
1054 Each Item has an optional ovf:configuration attribute, containing a list of configurations separated 1055 by a single space character. If not specified, the item shall be selected for any configuration. If specified, 1056 the item shall be selected only if the chosen configuration ID is in the list. A configuration attribute shall 1057 not contain an ID that is not specified in the DeploymentOptionSection. 1058 • Within a single VirtualHardwareSection or ResourceAllocationSection, multiple 1059 Item elements are allowed to refer to the same InstanceID. A single combined Item for the 1060 given InstanceID shall be constructed by picking up the child elements of each Item element, 1061 with child elements of a former Item element in the OVF descriptor not being picked up if there 1062 is a like-named child element in a latter Item element. Any attributes specified on child 1063 elements of Item elements that are not picked up that way, are not part of the combined Item 1064 element. 1065 • All Item elements shall specify ResourceType, and Item elements with the same InstanceID 1066 shall agree on ResourceType. 1067 EXAMPLE: The following example shows a VirtualHardwareSection: 1068
Version 1.0.0d 31 Open Virtualization Format Specification DSP0243
1075
1090 Note that the attributes ovf:configuration and ovf:bound on Item can be used in combination to 1091 provide very flexible configuration options.
1092 Configurations can further be used to control default values for properties. For Property elements inside 1093 a ProductSection, the following additional semantic is defined:
1094 • It is possible to use alternative default property values for different configurations in a 1095 DeploymentOptionSection. In addition to a Label and Description element, each 1096 Property element may optionally contain Value elements. The Value element shall have 1097 an ovf:value attribute specifying the alternative default and an ovf:configuration 1098 attribute specifying the configuration in which this new default value should be used. Multiple 1099 Value elements shall not refer to the same configuration. 1100 EXAMPLE: The following shows an example ProductSection: 1101
1109 9.9 OperatingSystemSection
1110 An OperatingSystemSection specifies the operating system installed on a virtual machine. 1111
1115 The valid values for ovf:id are defined by the ValueMap qualifier in the 1116 CIM_OperatingSystem.OsType property.
1117 OperatingSystemSection is a valid section for a VirtualSystem entity only.
32 Version 1.0.0d DSP0243 Open Virtualization Format Specification
1118 9.10 InstallSection
1119 The InstallSection, if specified, indicates that the virtual machine needs to be booted once in order 1120 to install and/or configure the guest software. The guest software is expected to access the OVF 1121 environment during that boot, and to shut down after having completed the installation and/or 1122 configuration of the software, powering off the guest.
1123 If the InstallSection is not specified, this indicates that the virtual machine does not need to be 1124 powered on to complete installation of guest software. 1125
1130 InstallSection is a valid section for a VirtualSystem entity only.
1131 The optional ovf:initialBootStopDelay attribute specifies a delay in seconds to wait for the virtual 1132 machine to power off. If not set, the implementation shall wait for the virtual machine to power off by itself. 1133 If the delay expires and the virtual machine has not powered off, the OVF application shall indicate a 1134 failure.
1135 Note that the guest software in the virtual machine can do multiple reboots before powering off.
1136 Several VMs in a virtual machine collection may have an InstallSection defined, in which case the 1137 above step is done for each VM, potentially concurrently.
1138 10 Internationalization
1139 The following elements support localizable messages using the optional ovf:msgid attribute: 1140 • Info element on Content 1141 • Info element on Section 1142 • Annotation element on AnnotationSection 1143 • License element on EulaSection 1144 • Description element on NetworkSection 1145 • Description element on OperatingSystemSection 1146 • Description, Product, Vendor, Label, and Category elements on ProductSection 1147 • Description and Label elements on DeploymentOptionSection 1148 • ElementName, Caption and Description subelements on the System element in 1149 VirtualHardwareSection 1150 • ElementName, Caption and Description subelements on Item elements in 1151 VirtualHardwareSection 1152 • ElementName, Caption and Description subelements on Item elements in 1153 ResourceAllocation
1154 The ovf:msgid attribute contains an identifier that refers to a message that can have different values in 1155 different locales.
Version 1.0.0d 33 Open Virtualization Format Specification DSP0243
1156 EXAMPLE 1: 1157
1160 The xml:lang attribute on the Envelope element specifies the default locale for messages in the 1161 descriptor. If not specified, the locale defaults to the locale of the consumer of the OVF package.
1162 Message resource bundles can be internal or external to the OVF descriptor. Internal resource bundles 1163 are represented as Strings elements at the end of the Envelope element.
1164 EXAMPLE 2: 1165
1180 External resource bundles shall be listed first in the References section and referred to from Strings 1181 elements. An external message bundle follows the same schema as the embedded one.
1182 EXAMPLE 3: 1183
1193 EXAMPLE 4: Example content of external resources/it-it-bundle.msg file, which is referenced in previous example: 1194
1201 The embedded and external Strings elements can be interleaved, but they shall be placed at the end of 1202 the Envelope element. If multiple occurrences of a msg:id attribute with a given locale occurs, a latter 1203 value overwrites a former.
34 Version 1.0.0d DSP0243 Open Virtualization Format Specification
1204 11 OVF Environment
1205 The OVF environment defines how the guest software and the deployment platform interact. This 1206 environment allows the guest software to access information about the deployment platform, such as the 1207 user-specified values for the properties defined in the OVF descriptor.
1208 The environment specification is split into a protocol part and a transport part. The protocol part defines 1209 the format and semantics of an XML document that can be made accessible to the guest software. The 1210 transport part defines how the information is communicated between the deployment platform and the 1211 guest software.
1212 The ovf-environment.xsd XML schema definition file for the OVF environment contains the elements 1213 and attributes.
1214 11.1 Environment Document
1215 The environment document is an extensible XML document that is provided to the guest software about 1216 the environment in which it is being executed. The way that the document is obtained depends on the 1217 transport type.
1218 EXAMPLE: An example of the structure of the OVF environment document follows: 1219 1220
1241 The PlatformSection element contains optional information provided by the deployment platform. 1242 Elements Kind, Version, and Vendor describe deployment platform vendor details. Elements Locale 1243 and TimeZone describe the current locale and time zone.
1244 The PropertySection element contains Property elements that correspond to those defined in the 1245 OVF descriptor for the current virtual machine. The environment presents properties as a simple list to 1246 make it easy for applications to parse. Furthermore, the single list format supports the override semantics 1247 where a property on a VirtualSystem can override one defined on a parent 1248 VirtualSystemCollection. The overridden property will not be in the list.
Version 1.0.0d 35 Open Virtualization Format Specification DSP0243
1249 The value of the ovfenv:id attribute of the Environment element shall match the value of the ovf:id 1250 attribute of the VirtualSystem entity describing this virtual machine The Property section contains 1251 the key/value pairs defined for all the properties specified in the OVF descriptor for the current virtual 1252 machine, as well as properties specified for the immediate parent VirtualSystemCollection, if one 1253 exists.
1254 An Entity element shall exist for each sibling VirtualSystem and VirtualSystemCollection, if 1255 any are present. The value of the ovfenv:id attribute of the Entity element shall match the value of 1256 the ovf:id attribute of the sibling entity. The Entity elements contain the property key/value pairs in 1257 the siblings OVF environment documents. This information can be used, for example, to make 1258 configuration information such as IP addresses available to VirtualSystems being part of a multi-tiered 1259 application.
1260 The environment document is extensible by providing new section types. A consumer of the document 1261 should ignore unknown section types and elements.
1262 11.2 Transport
1263 The environment document information can be communicated in a number of ways to the guest software. 1264 These ways are called transport types. The transport types are specified in the OVF descriptor by the 1265 ovf:transport attribute of VirtualHardwareSection. Several transport types may be specified, 1266 separated by a single space character, in which case an implementation is free to use any of them.
1267 The transport types define methods by which the environment document is communicated from the 1268 deployment platform to the guest software. Standardizing transport types does pose some challenges, 1269 since no industry-standard cross-vendor para-virtualized device exists. Possible transports types includes 1270 dynamically generated DVD images, dynamically generated floppy images, XenSource XenBus, 1271 Microsoft VMBus, VMware VMCI, and so on.
1272 To enable interoperability, OVF requires all implementations that support CD-ROM devices to support the 1273 "iso" transport type. This transport communicates the environment document by making a dynamically 1274 generated ISO image available to the guest software. To support the iso transport type, prior to booting 1275 a virtual machine, an implementation shall make an ISO 9660 read-only disk image available as backing 1276 for a disconnected CD-ROM. If the iso transport is selected for a VirtualHardwareSection, at least 1277 one disconnected CD-ROM device shall be present in this section.
1278 Support for the "iso" transport type is not a requirement for virtual hardware architectures or guest 1279 operating systems which do not have CD-ROM device support.
1280 The ISO image shall contain the OVF environment for this particular virtual machine, and the environment 1281 shall be present in an XML file named ovf-env.xml that is contained in the root directory of the ISO 1282 image. The guest software can now access the information using standard guest operating system tools.
1283 If the virtual machine prior to booting had more than one disconnected CD-ROM, the guest software may 1284 have to scan connected CD-ROM devices in order to locate the ISO image containing the ovf-env.xml 1285 file.
1286 To be compliant with this specification, any transport format other than iso shall be given by a URI which 1287 identifies an unencumbered specification on how to use the transport. The specification need not be 1288 machine readable, but it shall be static and unique so that it may be used as a key by software reading an 1289 OVF descriptor to uniquely determine the format. The specification shall be sufficient for a skilled person 1290 to properly interpret the transport mechanism for implementing the protocols. It is recommended that 1291 these URIs are resolvable.
36 Version 1.0.0d DSP0243 Open Virtualization Format Specification
1292 ANNEX A 1293 (informative) 1294 1295 Symbols and Conventions
1296 XML examples use the XML namespace prefixes defined in Table 1. The XML examples use a style to 1297 not specify namespace prefixes on child elements. Note that XML rules define that child elements 1298 specified without namespace prefix are from the namespace of the parent element, and not from the 1299 default namespace of the XML document.Throughout the document, whitespace within XML element 1300 values is used for readability. In practice, a service can accept and strip leading and trailing whitespace 1301 within element values as if whitespace had not been used.
1302 Syntax definitions in Augmented BNF (ABNF) use ABNF as defined in IETF RFC 2234 with the following 1303 exceptions:
1304 • Rules separated by a bar (|) represent choices, instead of using a forward slash (/) as defined in 1305 ABNF.
1306 • Any characters must be processed case sensitively, instead of case-insensitively as defined in 1307 ABNF.
1308 • Whitespace (i.e. the space character U+0020 and the tab character U+0009) is allowed between 1309 syntactical elements, instead of assembling elements without white space as defined in ABNF.
1310
Version 1.0.0d 37 Open Virtualization Format Specification DSP0243
1311 ANNEX B 1312 (informative) 1313 1314 Change Log
Version Date Description
1.0.0a 2008-06-04 Work in progress release
1.0.0b 2008-07-23 Preliminary release
Revised XML schemas to use substitution groups
1.0.0c 2008-08-13 Preliminary release
Errata
1.0.0d 2008-08-18 Preliminary release
1315
38 Version 1.0.0d DSP0243 Open Virtualization Format Specification
1316 ANNEX C 1317 (normative) 1318 1319 OVF XSD
1320 A normative copy of the XML schemas for this specification may be retrieved by resolving a URL which 1321 consists of the XML namespace URI for the XML schema, followed by 1322 "/
1323 Any xs:documentation content in XML schemas for this specification is informative and provided only 1324 for convenience.
1325 Normative copies of the XML schemas for the WS-CIM mapping (DSP0230) of 1326 CIM_ResourceAllocationSystemSettingsData andCIM_VirtualSystemSettingData may be 1327 retrieved by resolving the following XML namespace URIs below. Note that ".xsd" has to be appended 1328 to the URIs. 1329 xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim- 1330 schema/2/CIM_VirtualSystemSettingData" 1331 xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim- 1332 schema/2/CIM_ResourceAllocationSettingData"
1333 This specification is based on the following CIM MOFs: 1334 CIM_VirtualSystemSettingData.mof 1335 CIM_ResourceAllocationSettingData.mof 1336 CIM_OperatingSystem.mof
Version 1.0.0d 39