Import and export VMs

Citrix Hypervisor allows you to import VMs from and export them to various different formats. Using the XenCenter Import wizard, you can import VMs from disk images (VHD and VMDK), Open Virtualization Format (OVF and OVA) and Citrix Hypervisor XVA format. You can even import VMs that have been created on other virtualization platforms, such as those offered by VMware and Microsoft.

Note:

When importing VMs that have been created using other virtualization platforms, configure or fix up the guest operating system to ensure that it boots on Citrix Hypervisor. The Operating System Fixup feature in XenCenter aims to provide this basic level of interoperability. For more information, see Operating system fixup.

Using the XenCenter Export wizard, you can export VMs to Open Virtualization Format (OVF and OVA) and Citrix Hypervisor XVA format.

You can also use the xe CLI to import VMs from and export them to Citrix Hypervisor XVA format.

Requirements

To be able to import and export VMs to and from different formats, you require certain permissions. The Import or Export wizard performs checks to ensure that you have a required role in the destination pool before allowing you to continue. For more information about the RBAC roles that are required, see RBAC roles and permissions.

Supported formats

Which format to use?

Consider using OVF/OVA format to:

• Share Citrix Hypervisor vApps and VMs with other virtualization platforms that support OVF

• Save more than one VM

• Secure a vApp or VM from corruption and tampering

• Include a license agreement

• Simplify vApp distribution by storing an OVF package in an OVA file

Consider using XVA format to:

• Import and export VMs from a script with a CLI

Open virtualization format (OVF and OVA)

OVF is an open standard, specified by the Distributed Management Task Force, for packaging and distributing a virtual appliance consisting of one or more VMs. For further details about OVF and OVA formats, see the following information:

• Open Virtualization Format Specification

An OVF Package is the set of files that comprises the virtual appliance. It always includes a descriptor file and any other files that represent the following attributes of the package:

Attributes

Descriptor (.ovf): The descriptor always specifies the virtual hardware requirements of the package. It may also specify other information, including:

• Descriptions of virtual disks, the package itself, and guest operating systems
• A license agreement
• Instructions to start and stop VMs in the appliance
• Instructions to install the package

Signature (.cert): The signature is the digital signature used by a public key certificate in the X.509 format to authenticate the author of the package.

Manifest (.mf): The manifest allows you to verify the integrity of the package contents. It contains the SHA-1 digests of every file in the package.

Virtual disks: OVF does not specify a disk image format. An OVF package includes files comprising virtual disks in the format defined by the virtualization product that exported the virtual disks. Citrix Hypervisor produces OVF packages with disk images in Dynamic VHD format; VMware products and Virtual Box produce OVF packages with virtual disks in Stream-Optimized VMDK format.

OVF packages also support other non-metadata related capabilities, such as compression, archiving, EULA attachment, and annotations.

Note:

When importing an OVF package that has been compressed or contains compressed files, you may need to free up extra disk space on the Citrix Hypervisor server to import it properly.

An Open Virtual Appliance (OVA) package is a single archive file, in the Tape Archive (.tar) format, containing the files that comprise an OVF Package.

Select OVF or OVA format

OVF packages contain a series of uncompressed files, which makes it easier when you want to access individual disk images in the file. An OVA package contains one large file, and while you can compress this file, it does not give you the flexibility of a series of files.

Using the OVA format is useful for specific applications for which it is beneficial to have just one file, such as creating packages for Web downloads. Consider using OVA only as an option to make the package easier to handle. Using this format lengthens both the export and import processes.

Disk image formats (VHD and VMDK)

Using XenCenter, you can import disk images in the Virtual Hard Disk (VHD) and Virtual Machine Disk (VMDK) formats. Exporting standalone disk images is not supported.

You might choose to import a disk image when a virtual disk image is available without any associated OVF metadata. This option might occur in the following situations:

• It is possible to import a disk image, but the associated OVF metadata is not readable

• A virtual disk is not defined in an OVF package

• You are moving from a platform that does not allow you to create an OVF package (for example, older platforms or images)

• You want to import an older VMware appliance that does not have any OVF information

• You want to import a standalone VM that does not have any OVF information

When available, we recommend importing appliance packages that contain OVF metadata rather than an individual disk image. The OVF data provides information the Import wizard requires to recreate a VM from its disk image, This information includes the number of disk images associated with the VM, the processor, storage, network, memory requirements and so on. Without this information, it can be much more complex and error-prone to recreate the VM.

XVA format

XVA is a virtual appliance format specific to Citrix Hypervisor, which packages a single VM as a single set of files, including a descriptor and disk images. The file name extension is .xva.

The descriptor (file name extension ova.xml) specifies the virtual hardware of a single VM.

The disk image format is a directory of files. The directory name corresponds to a reference name in the descriptor and contains two files for each 1 MB block of the disk image. The base name of each file is the block number in decimal. The first file contains one block of the disk image in raw binary format and does not have an extension. The second file is a checksum of the first file. If the VM was exported from Citrix Hypervisor 8.0 or earlier, this file has the extension .checksum. If the VM was exported from Citrix Hypervisor 8.1 or later, this file has the extension .xxhash.

Important:

If a VM is exported from the Citrix Hypervisor server and then imported into another Citrix Hypervisor server with a different CPU type, it may not run properly. For example, a Windows VM exported from a host with an Intel® VT Enabled CPU might not run when imported into a host with an AMD-VTM CPU.

Operating system fixup

When importing a virtual appliance or disk image created and exported from a virtualization platform other than Citrix Hypervisor, you might have to configure the VM before it boots properly on the Citrix Hypervisor server.

XenCenter includes an advanced hypervisor interoperability feature – Operating System Fixup – which aims to ensure a basic level of interoperability for VMs that you import into Citrix Hypervisor. Use Operating System Fixup when importing VMs from OVF/OVA packages and disk images created on other virtualization platforms.

The Operating System Fixup ISO is located in your XenCenter installation in the directory C:\Program Files (x86)\XenServer\XenCenter\External Tools.

The Operating System Fixup process addresses the operating system device and driver issues inherent when moving from one hypervisor to another. The process attempts to repair boot device-related problems with the imported VM that might prevent the operating system within from booting in the Citrix Hypervisor environment. This feature is not designed to perform conversions from one platform to another.

Note:

This feature requires an ISO storage repository with 40 MB of free space and 256 MB of virtual memory.

Operating System Fixup is supplied as an automatically booting ISO image that is attached to the DVD drive of the imported VM. It performs the necessary repair operations when the VM is first started, and then shuts down the VM. The next time the new VM is started, the boot device is reset, and the VM starts normally.

To use Operating System Fixup on imported disk images or OVF/OVA packages, enable the feature on the Advanced Options page of the XenCenter Import wizard. Specify a location where the Fixup ISO is copied so that Citrix Hypervisor can use it.

What does operating system fixup do to the VM?

The Operating System Fixup option is designed to make the minimal changes possible to enable a virtual system to boot. Depending on the guest operating system and the hypervisor of the original host, further actions might be required after using Operating System Fixup. These actions can include configuration changes and driver installation.

During the Fixup process, an ISO is copied to an ISO SR. The ISO is attached to a VM. The boot order is set to boot from the virtual DVD drive, and the VM boots into the ISO. The environment within the ISO then checks each disk of the VM to determine if it is a Linux or a Windows system.

If a Linux system is detected, the location of the GRUB configuration file is determined. Any pointers to SCSI disk boot devices are modified to point to IDE disks. For example, if GRUB contains an entry of /dev/sda1 representing the first disk on the first SCSI controller, this entry is changed to /dev/hda1 representing the first disk on the first IDE controller.

If a Windows system is detected, a generic critical boot device driver is extracted from the driver database of the installed OS and registered with the OS. This process is especially important for older Windows operating systems when the boot device is changed between a SCSI and IDE interface.

If certain virtualization tool sets are discovered in the VM, they are disabled to prevent performance problems and unnecessary event messages.

Import VMs

When you import a VM, you effectively create a VM, using many of the same steps required to provision a new VM. These steps include nominating a host, and configuring storage and networking.

You can import OVF/OVA, disk image, XVA, and XVA Version 1 files using the XenCenter Import wizard. You can also import XVA files via the xe CLI.

Import VMs from OVF/OVA

The XenCenter Import wizard allows you to import VMs that have been saved as OVF/OVA files. The Import wizard takes you through the usual steps to create a VM in XenCenter: nominating a host, and then configuring storage and networking for the new VM. When importing OVF and OVA files, extra steps may be required, such as:

• When importing VMs that have been created using other virtualization platforms, run the Operating System Fixup feature to ensure a basic level of interoperability for the VM. For more information, see Operating system fixup.

Prerequisites

• Ensure that the target host has enough RAM to support the virtual machines being imported. A lack of available RAM results in a failed import.

Imported OVF packages appear as vApps when imported using XenCenter. When the import is complete, the new VMs appear in the XenCenter Resources pane, and the new vApp appears in the Manage vApps dialog box.

To import VMs from OVF/OVA by using XenCenter:

1. Open the Import wizard by doing one of the following:

   • In the Resources pane, right-click, and then select Import on the shortcut menu.
   • On the File menu, select Import.

2. On the first page of the wizard, locate the file you want to import, and then click Next to continue.

3. Review and accept EULAs, if applicable.

   If the package you are importing includes any EULAs, accept them and click Next to continue. When no EULAs are included in the package, the wizard skips this step and advances straight to the next page.

4. Specify the pool or host to which you want to import the VMs. To select a host or pool, choose from the Import VM(s) to list.

   Click Next to continue.

5. Configure storage for the imported VMs: Choose one or more storage repositories on which to place the imported virtual disks, and then click Next to continue.

   To place all the imported virtual disks on the same SR, select Place all imported VMs on this target SR. Select an SR from the list.

   To place the virtual disks of incoming VMs onto different SRs, select Place imported VMs on the specified target SRs. For each VM, select the target SR from the list in the SR column.

6. Configure networking for the imported VMs: map the virtual network interfaces in the VMs you are importing to target networks in the destination pool. The Network and MAC address shown in the list of incoming VMs are stored as part of the definition of the original (exported) VM in the export file. To map an incoming virtual network interface to a target network, select a network from the list in the Target Network column. Click Next to continue.

7. Specify security settings: If the selected OVF/OVA package is configured with security features, such as certificates or a manifest, specify the information necessary, and then click Next to continue.

   Different options appear on the Security page depending on which security features have been configured on the OVF appliance:

   • If the appliance is signed, a Verify digital signature check box appears, automatically selected. Click View Certificate to display the certificate used to sign the package. If the certificate appears as untrusted, it is likely that either the Root Certificate or the Issuing Certificate Authority is not trusted on the local computer. Clear the Verify digital signature check box if you do not want to verify the signature.

   • If the appliance includes a manifest, a Verify manifest content check box appears. Select this check box to have the wizard verify the list of files in the package.

   When packages are digitally signed, the associated manifest is verified automatically, so the Verify manifest content check box does not appear on the Security page.

   Note:

   VMware Workstation 7.1.x OVF files fail to import when you choose to verify the manifest. This failure occurs because VMware Workstation 7.1.x produces an OVF file with a manifest that has invalid SHA-1 hashes. If you do not choose to verify the manifest, the import is successful.

8. Enable Operating System Fixup: If the VMs in the package you are importing were built on a virtualization platform other than Citrix Hypervisor, select the Use Operating System Fixup check box. Select an ISO SR where the Fixup ISO can be copied so that Citrix Hypervisor can access it. For more information about this feature, see Operating system fixup.

   Click Next to continue.

9. Review the import settings, and then click Finish to begin the import process and close the wizard.

   Note:

   Importing a VM may take some time, depending on the size of the VM and the speed and bandwidth of the network connection.

The import progress is displayed in the status bar at the bottom of the XenCenter window and on the Logs tab. When the newly imported VM is available, it appears in the Resources pane, and the new vApp appears in the Manage vApps dialog box.

Note:

After using XenCenter to import an OVF package that contains Windows operating systems, you must set the platform parameter.

1. Set the platform parameter to device_id=0002. For example:

   xe vm-param-set uuid=VM uuid platform:device_id=0002
   

2. Set the platform parameter to viridian=true. For example:

   xe vm-param-set uuid=VM uuid platform:viridian=true
   

Import disk images

The XenCenter Import wizard allows you to import a disk image into a pool or specific host as a VM. The Import wizard takes you through the usual steps to create a VM in XenCenter: nominating a host, and then configuring storage and networking for the new VM.

Prerequisites

• Ensure that DHCP runs on the management network Citrix Hypervisor is using.

• The Import wizard requires local storage on the server on which you are running it.

To import VMs from a Disk Image by using XenCenter:

1. Open the Import wizard by doing one of the following:

   • In the Resources pane, right-click, and then select Import on the shortcut menu.

   • On the File menu, select Import.

2. On the first page of the wizard, locate the file you want to import, and then click Next to continue.

3. Specify the VM name and allocate CPU and memory resources.

   On the VM Definition page, enter the name of the new VM to be created from the imported disk image, and allocate CPU and initial memory resources. All of these values can be adjusted later, after the new VM has been created. For more information, see VM CPU and Memory Allocation. VM names are not checked for uniqueness within XenCenter, so it makes it easier for you to manage different VMs if you give them meaningful, memorable names. For more information, see VM Name and Description.

   Click Next to continue.

4. Specify the pool or host to which you want to import the VMs. To select a host or pool, choose from the Import VM(s) to list.

   Click Next to continue.

5. Configure storage for the imported VMs: Select one or more storage repositories on which to place the imported virtual disks, and then click Next to continue.

   To place all the imported virtual disks on the same SR, select Place all imported VMs on this target SR. Select an SR from the list.

   To place the virtual disks of incoming VMs onto different SRs, select Place imported VMs on the specified target SRs. For each VM, select the target SR from the list in the SR column.

6. Configure networking for the imported VMs: map the virtual network interfaces in the VM you are importing to target networks in the destination pool. The Network and MAC address shown in the list of incoming VMs are stored as part of the definition of the original (exported) VM in the export file. To map an incoming virtual network interface to a target network, select a network from the list in the Target Network column. Click Next to continue.

7. Specify the boot option.

   On the Boot options page, specify the boot mode for the new VM. Select BIOS Boot to boot the VM in legacy BIOS mode.

   Citrix Hypervisor supports UEFI boot on certain operating systems. For more information about the guest operating systems that are supported for UEFI boot, see Guest UEFI boot and Secure Boot.

   Select UEFI Boot to boot the VM in UEFI mode.

8. Enable Operating System Fixup: If the disk images you are importing were built on a virtualization platform other than Citrix Hypervisor, select the Use Operating System Fixup check box. Select an ISO SR where the Fixup ISO can be copied so that Citrix Hypervisor can access it. For more information about this feature, see Operating system fixup.

   Click Next to continue.

9. Review the import settings, and then click Finish to begin the import process and close the wizard.

   Note:

   Importing a VM may take some time, depending on the size of the VM and the speed and bandwidth of the network connection.

The import progress is displayed in the status bar at the bottom of the XenCenter window and on the Logs tab. When the newly imported VM is available, it appears in the Resources pane.

Note:

After using XenCenter to import a disk image that contains Windows operating systems, you must set the platform parameter. The value of this parameter varies according to the version of Windows contained in the disk image:

• For Windows Server 2016 and later, set the platform parameter to device_id=0002. For example:

   xe vm-param-set uuid=VM uuid platform:device_id=0002
   <!--NeedCopy-->
  

• For all other versions of Windows, set the platform parameter to viridian=true. For example:

   xe vm-param-set uuid=VM uuid platform:viridian=true
   <!--NeedCopy-->
  

Import VMs from XVA

Note:

The VM Admin role can only import XVA files into a pool with a shared SR. The VM Admin role does not have permission to import an XVA file into a server or a pool without shared storage.

You can import VMs, templates, and snapshots that have previously been exported and stored locally in XVA format (.xva). To do so, you follow the usual steps to create a VM: nominating a host, and then configuring storage and networking for the new VM.

Warning:

It may not always be possible to run an imported VM that was exported from another server with a different CPU type. For example, a Windows VM exported from a server with an Intel VT Enabled CPU might not run when imported to a server with an AMD-VTM CPU.

To import VMs from XVA by using XenCenter:

1. Open the Import wizard by doing one of the following:

   • In the Resources pane, right-click, and then select Import on the shortcut menu.
   • On the File menu, select Import.

2. On the first page of the wizard, locate the file you want to import (.xva or ova.xml), and then click Next to continue.

   If you enter a URL location (http, https, file, or ftp) in the Filename box. Click Next, a Download Package dialog box opens and you must specify a folder on your XenCenter host where the file is copied.

3. Select a pool or host for the imported VM to start on, and then choose Next to continue.

4. Select the storage repositories on which to place the imported virtual disk, and then click Next to continue.

5. Configure networking for the imported VMs: map the virtual network interface in the VM you are importing to target a network in the destination pool. The Network and MAC address shown in the list of incoming VMs are stored as part of the definition of the original (exported) VM in the export file. To map an incoming virtual network interface to a target network, select a network from the list in the Target Network column. Click Next to continue.

6. Review the import settings, and then click Finish to begin the import process and close the wizard.

   Note:

   Importing a VM may take some time, depending on the size of the VM and the speed and bandwidth of the network connection.

The import progress is displayed in the status bar at the bottom of the XenCenter window and on the Logs tab. When the newly imported VM is available, it appears in the Resources pane.

To import a VM from XVA by using the xe CLI:

To import the VM to the default SR on the target Citrix Hypervisor server, enter the following:

xe vm-import -h hostname -u root -pw password \
    filename=pathname_of_export_file
<!--NeedCopy-->

To import the VM to a different SR on the target Citrix Hypervisor server, add the optional sr-uuid parameter:

xe vm-import -h hostname -u root -pw password \
    filename=pathname_of_export_file sr-uuid=uuid_of_target_sr
<!--NeedCopy-->

If you want to preserve the MAC address of the original VM, add the optional preserve parameter and set to true:

xe vm-import -h hostname -u root -pw password \
    filename=pathname_of_export_file preserve=true
<!--NeedCopy-->

Note:

Importing a VM may take some time, depending on the size of the VM and the speed and bandwidth of the network connection.

After the VM has been imported, the command prompt returns the UUID of the newly imported VM.

Export VMs

You can export OVF/OVA and XVA files using the XenCenter Export wizard; you can also export XVA files via the xe CLI.

Export VMs as OVF/OVA

Using the XenCenter Export wizard, you can export one or more VMs as an OVF/OVA package. When you export VMs as an OVF/OVA package, the configuration data is exported along with the virtual hard disks of each VM.

To export VMs as OVF/OVA by using XenCenter:

1. Shut down or suspend the VMs that you want to export.

2. Open the Export wizard: in the Resources pane, right-click the pool or host containing the VMs you want to export, and then select Export.

3. On the first page of the wizard:
   • Enter the name of the export file
   • Specify the folder where you want the files to be saved
   • Select OVF/OVA Package (*.ovf, *.ova) from the Format list
   • Click Next to continue

4. From the list of available VMs, select the VMs that you want to include in the OVF/OVA package, and then click Next to continue.

5. If necessary, you can add to a previously prepared End User Licensing Agreement (EULA) document (.rtf, .txt) to the package.

   To add a EULA, click Add and browse to the file you want to add. Once you have added the file, you can view the document by selecting it from the EULA files list and then clicking View.

   EULAs can provide the legal terms and conditions for using the appliance and the applications delivered in the appliance.

   The ability to include one or more EULAs lets you legally protect the software on the appliance. For example, if your appliance includes a proprietary operating system on its VMs, you might want to include the EULA text from that operating system. The text is displayed and the person who imports the appliance must accept it.

   Note:

   Attempting to add EULA files that are not in supported formats, including XML or binary files, can cause the import EULA functionality to fail.

   Select Next to continue.

6. On the Advanced options page, specify a manifest, signature and output file options, or just click Next to continue.

   1. To create a manifest for the package, select the Create a manifest check box.

      The manifest provides an inventory or list of the other files in a package. The manifest is used to ensure that the files originally included when the package was created are the same files present when the package arrives. When the files are imported, a checksum is used to verify that the files have not changed since the package was created.

   2. To add a digital signature to the package

      1. Select Sign the OVF package.

         The digital signature (.cert) contains the signature of the manifest file and the certificate used to create that signature. When a signed package is imported, the user can verify the identity of the package creator by using the public key of the certificate to validate the digital signature.

      2. Browse to locate a certificate.

         Use an X.509 certificate that you have already created from a Trusted Authority and exported as a .pfx file. For certificates with SHA-256 digest export using the “Microsoft Enhanced RSA and AES Cryptographic Provider” as CSP.

      3. In Private key password enter the export (PFX) password, or, if an export password was not provided, the private key associated with the certificate.

   3. To output the selected VMs as a single (tar) file in OVA format, select the Create OVA package (single OVA export file) check box. For more on the different file formats, see Open virtualization format.

   4. To compress virtual hard disk images (.VHD files) included in the package, select the Compress OVF files check box.

      When you create an OVF package, the virtual hard disk images are, by default, allocated the same amount of space as the exported VM. For example, a VM that is allocated 26 GB of space has a hard disk image that consumes 26 GB of space. The hard disk image uses this space regardless of whether or not the VM actually requires it.

      Note:

      Compressing the VHD files makes the export process take longer to complete. Importing a package containing compressed VHD files also takes longer, as the Import wizard must extract all of the VHD images as it imports them.

   If both Create OVA package (single OVA export file) and Compress OVF files are checked, the result is a compressed OVA file with the extension .ova.gz.

7. Review the export settings.

   To have the wizard verify the exported package, select the Verify export on completion check box. Click Finish to begin the export process and close the wizard.

   Note:

   Exporting a VM may take some time, depending on the size of the VM and the speed and bandwidth of the network connection.

The export progress is displayed in the status bar at the bottom of the XenCenter window and on the Logs tab. To cancel an export in progress, click the Logs tab, find the export in the list of events, and click the Cancel button.

Export VMs as XVA

You can export an existing VM as an XVA file using the XenCenter Export wizard or the xe CLI. We recommend exporting a VM to a machine other than the Citrix Hypervisor server, on which you can maintain a library of export files. For example, you can export the VM to the machine running XenCenter.

Warning:

It may not always be possible to run an imported VM that was exported from another server with a different CPU type. For example, a Windows VM exported from a server with an Intel VT Enabled CPU might not run when imported to a server with an AMD-VTM CPU.

To export VMs as XVA files by using XenCenter:

1. Shut down or suspend the VM that you want to export.

2. Open the Export wizard: from the Resources pane, right-click the VM which you want to export, and then select Export.

3. On the first page of the wizard:
   • Enter the name of the export file
   • Specify the folder where you want the files to be saved
   • Select XVA File (*.xva) from the Format list
   • Click Next to continue

4. From the list of available VMs, select the VM that you want to export, and then click Next to continue.

5. Review the export settings.

   To have the wizard verify the exported package, select the Verify export on completion check box. Click Finish to begin the export process and close the wizard.

   Note:

   Exporting a VM may take some time, depending on the size of the VM and the speed and bandwidth of the network connection.

The export progress is displayed in the status bar at the bottom of the XenCenter window and on the Logs tab. To cancel an export in progress, click the Logs tab, find the export in the list of events, and click the Cancel button.

To export VMs as XVA files by using the xe CLI:

1. Shut down the VM that you want to export.

2. Export the VM by running the following:

   xe vm-export -h hostname -u root -pw password vm=vm_name \
       filename=pathname_of_file
   <!--NeedCopy-->
   

   Note:

   Be sure to include the .xva extension when specifying the export file name. If the exported VM doesn’t have this extension, XenCenter might fail to recognize the file as a valid XVA file when you attempt to import it.