Project Kensho v1.1 Technology Preview

Introduction Citrix Project Kensho provides administrators with highly usable tools that facilitate the export and import of virtual machines and virtual machine based workloads (virtual appliances) using the Open Virtual Machine Format (OVF) and Common Information Model (CIM) industry standards developed by the Distributed Management Task Force (DMTF). The Project Kensho OVF Tool utilizes the OVF standard for the export and import of virtual appliances. The Open Virtual Machine Format is an XML document that describes the metadata of virtual machine(s) that are stand alone or part of a virtual appliance along with pointers to the location of the virtual disks. Citrix Project Kensho also provides a CIM interface to the XenServer™ API. As well as introducing a WSMAN interface to XenServer™. The Xen-CIM component is required by the Project Kensho OVF Tool and installs directly on the XenServer™.  Project Kensho version 1.1 adds support for paravirtualized Linux guests, new CIM classes and deeper support for XenServer 5.0.

*MyCitrix login required for download   Resources   Discuss in Forum   Simon Crosby's Blog on Kensho   Video Project Kensho OVF Tool

Installing the Project Kensho OVF Tool

Installing XenServer CIM Interfaces

Using the Project Kensho OVF Tool

Creating a Virtual Appliance

Project Kensho consists of the following components:
An OVF Tool , which utilizes the OVF standard for the export and import of virtual appliances. The Open Virtual Machine Format is an XML document that describes the metadata of virtual machine(s) that are stand alone or part of a virtual appliance along with pointers to the location of the virtual disks.
A CIM interface to the XenServer™ API, which also adds a WSMAN interface to XenServer™. The Xen-CIM component is required by the Project Kensho OVF Tool and installs directly on the XenServer™. It can also be used as an interface for management of XenServer™ and XenServer™ hosted virtual machines.

Project Kensho System Requirements

The minimum environment for evaluation is: Project Kensho OVF Tool Host, a supported virtual machine host, and a Windows SMB share. Project Kensho requires the following services and software to support the components of the Project Kensho OVF Tool.

Software	Description
Project Kensho OVF Tool Host	To run the Project Kensho OVF Tool, you need a personal computer running Windows XP or Windows Server 2003.
Citrix XenServer™	Citrix XenServer™ 4.1 or 5.0 is required for importing and exporting OVF based virtual machines using XenServer™. The Project Kensho OVF Tool supports only VHD based virtual machines. Therefore to import to and export from XenServer™, the Project Kensho OVF Tool requires that a VHD or NFS based storage repository is mounted on the XenServer™ host. The Project Kensho Xen-CIM installation utility provides a configuration script to modify the default storage repository. This script is described in later sections of this document.
Windows Server 2008 with Hyper-V	The Project Kensho OVF Tool supports Windows Server 2008 with the Hyper-V Role for importing and exporting OVF based virtual appliances. You will need a local Windows Server 2008 user account, which is a member of the local server administrators group. Communication between the Project Kensho OVF Tool and the Windows Server occurs through WinRM. Windows Server 2008 installs WinRM by default, no additional installation is required. The WinRM service and firewall rules must be configured correctly. The Project Kensho installation utility provides a script to configure these services. This script is described in later sections of this document.
Windows Server SMB File Share	The Project Kensho OVF Tool requires a Windows based UNC share to import and export OVF packages. This is called the Kensho (or OVF) Library. The share must be accessible from the Project Kensho OVF Tool as well as any virtual machine hosts targeted for import or export.

Before you install

Complete the following pre-installation tasks before installing Project Kensho components:

1. Read through this entire document
2. File Share
   1. Create a file share from a Windows host
      1. Windows Server 2008 with the File Services Role provides the option of creating SMB or NFS based shares, be sure to select SMB.
      2. Windows Server 2003 and prior create SMB based shares by default.
   2. Obtain a user account and password that has change level access to this share.
3. Project Kensho OVF Tool Host
   1. Windows XP, Windows Server 2003, or Windows Vista.
   2. Install .NET Framework version 3.5
   3. Install Microsoft PowerShell 1.0
   4. Install WinRM
4. XenServer™ Host
   1. XenServer™ 4.1 or 5.0
   2. Local or NFS storage repository
5. Windows Server 2008 with Hyper-V Host
   1. Add the Hyper-V role
   2. Add the PowerShell feature

 

Xen- CIM Interface v1.1 Installation

To install the Xen-CIM Interface on XenServer™, complete the following procedure:

 

1. Copy Xen-CIM-Install.tgz to the XenServer™ host to the path of: /tmp
2. From the XenServer™ console, execute the following
   1. cd /tmp
   2. tar - xvzf XenServer-CIM-1.1.tgz
   3. cd /XenServer-CIM
   4. Attach a compatible storage repository to the XenServer host:
   5. Create a VHD based storage repository
   6. ./create-vhd-sr.sh
   7. Or, create an NFS repository by connecting to a NFS share.
   8. Install the Xen-CIM and WSMAN providers
   9. ./install.sh
      1. Answer the prompt to set the security level of the interface.

Project Kensho OVF Tool v1.1 Installation

1. From the computer identified as the Project Kensho OVF Tool computer
   1. Execute KenshoOVF_x86.msi
   2. Follow the prompts
   3. If upgrading from a Kensho OVF Tool 1.0 installation, a prompt will appear instructing to remove the Kensho OVF Tool 1.0 through Add / Remove Programs before continuing.

Windows Server 2008 with Hyper-V Configuration:

1. Install the Microsoft PowerShell Feature (required to run the configuration script)
2. Obtain the winrmconfigure.ps1 PowerShell script from the OVF Tool client.
   1. The PowerShell script can be found under the installation directory of the Kensho OVF Tool host i.e. C:\Program Files\Citrix\Kensho
3. Set the execution Policy to allow local script execution:
   1. From a PowerShell prompt execute: set-executionpolicy remotesigned
4. Enable the default WinRM HTTP listener for the Project Kensho OVF Tool
   1. From a PowerShell prompt execute: .* *winrmconfigure.ps1 service unsecure

 

Xen-CIM v1.1 Interface UnInstallation

1. To uninstall the Xen-CIM and WSMAN providers
   1. Cd /usr/local/XenServer-CIM
   2. ./uninstall.sh

Project Kensho OVF Tool v1.1 UnInstallation

1. From the computer identified as the Project Kensho OVF Tool computer
   1. Open Add / Remove Programs (or Programs)
   2. Select the Project Kensho OVF Tool
   3. Select Remove

 

Xen- CIM Interface

Once installed, the Xen-CIM interface requires no administration.
A "README.html" is provided within the distribution that further describes the interface and options.

Project Kensho OVF Tool

The Project Kensho OVF Tool is the primary application to import and export VHD based OVF virtual appliances.
When executing the application, the user is presented with the main window shown below.

Figure 1
- Project Kensho OVF Tool main Window

Adding virtual machine Host (s) and OVF Library Resources

To begin using the tool, it is necessary to add at least one virtual machine host and a Library.

To add a virtual machine host or Library share:

1.   In the main application window, select Choose File > Add Server . Alternatively you can press the hotkey combination Alt +A or click the Add Server icon on the toolbar.

2.   Select the platform type from the drop down menu: Library, XenServer™, or Hyper-V.

	For a Library : *## Enter the server name (or IP address) Enter the share name (without slashes or subfolders) Enter the username and password Click Add .
Figure 2 : Adding a Library using the Add Server dialog
	For a virtual machine host: Enter the server name (or IP address) Select the Host server protocol: Unsecure or Secure (HTTP/HTTPS) Enter the username and password Click Add
Figure 3 : Adding a XenServer™ host using the Add Server d ialog

3.  Click Close when finished. Repeat this process for each hypervisor and or library the Project Kensho OVF Tool will manage.

Exporting a VM(s) to an OVF package
After configuring a library and virtual machine host(s), the Kensho OVF Tool is ready to export one or more virtual machines as an OVF package.

To export a virtual machine, do the following:

1.   Select the Export Tab

Figure 4
- Completed Export Tab

2.   Select the target library share from the Library tree view. This is where the OVF and associated VHD(s) will reside after export.

3.   From the tree view, expand the list of virtual machines under each virtual machine host.

4.   Select a virtual machine with a single click. This will place its qualified name into the Selected vMachine(s) list box. To remove the selection, double click the selection.

5.   The Project Kensho OVF Tool has the ability to add an End User Licensing Agreement (EULA) to an OVF. This forces the user importing the OVF virtual machine(s) to accept the EULA before proceeding. To add a EULA, do the following prior to exporting:

      a ) Click the Add EULA button

      b ) Browse to the desired text file containing the EULA text.

      c ) Select the EULA text file.

      d ) Click Open.

Export Metadata Only Option: This option exports only the virtual machine(s) configuration (metadata)and does not export the virtual hard disks associated with any of the virtual machines.
To only export the OVF metadata, select the checkbox.

6.   Click Export to begin the Export

Importing an OVF package to a virtual machine host(s)
The Project Kensho OVF Tool facilitates the import of any DMTF compliant OVF file that contains virtual machine disk(s) in the VHD format.
To import an OVF with the Project Kensho OVF Tool:

1.   Select the Import tab

Figure 5
- The Import Tab window
2.   Select the target virtual machine host or hosts from the respective Host type tree view.
3.   From the Kensho Library tree view, select an OVF.

Import Metadata Only Option: The Import Metadata Only option creates the virtual machine(s) contained within a package and does not import any virtual hard disks referenced in the package.
4.   If a virtual machine to host resource mapping is required - it is noted in the Mapping status field as Mapping: Required.
5.   Click the Mapping wizard button in the Tool bar to map virtual machine to host resources.
  &nbsp a) See Resource Mapping below for full detail.

6.   Click the Import or Force button to begin the import.

7.   If the OVF requires EULA acceptance the following dialog will be presented containing the text of the EULA:

Figure 6 : EULA Dialog

VM to Host Resource Mapping Wizard

The Project Kensho OVF Tool allows administrators to map system, storage, and networking resources defined in the OVF package to the resources of the virtual machine host(s). This ensures that prior to import, the proper resources are paired and the virtual machine can power on without any further administrative tasks.
Mapping is performed by selecting items (one or more) in the left column of the Mapping dialog and then selecting a target device in the right.
The padlock icon depicts that a mapping of a VM device to Host resource has been set. Individual mappings may be cleared by selecting and clearing the lock icon.
An existing OVF to Host resource mapping may be cleared by clicking the "Clear" button on the Import tab.
1.   Begin the resource mapping process by Clicking the Mapping button in the Tool bar
2.   The mapping wizard launches and presents the Systems tab (this is the target Host for a VM workload).

Figure 7 : Unmapped VM CPU and memory workload
3.   Select the desired host resource in the right pane
4.   Select a VM resource(s) in the left pane

Figure 8 : VM CPU and memory workload mapped to H ost
5.   Click Next to map the Network resources

Figure 9 : Mapped VM Network Device to Hypervisor Network Device
6.   Select the desired host resource in the right pane
7.   Select a VM resource(s) in the left pane
8.   Click Next to map the Storage resources

Figure 10 : Mapped VM Storage to Hypervisor Storage

9.    Select the desired host resource in the right pane
10.   Select a VM resource(s) in the left pane
11.   Click Done to complete the wizard, save the mapping, and return to the Import screen.

Converting an OVF package to an OVA and vice versa

The Project Kensho OVF Tool facilitates the conversion of a DMTF compliant OVF export and VHD to a single OVA file.  The purpose of an OVA is to act as the distribution medium of a virtual appliance.  The output is in an uncompressed TAR format with a .ova extension.  Any OVF in a library can be converted into an OVA and vice versa.  To import an OVA, it must first be unpackaged into an OVF Package directory, then imported.

To convert an OVF with the Project Kensho OVF Tool:

1.   Select the Import tab

Figure 11 : Import Tab

2.   From the Kensho Library, select an OVF.
3.   Right click the OVF and Select 'Convert to OVA'
4.   The reverse process is used to convert an OVA into an OVF.

Environment Tab
The environment tab is a read-only view of the virtual machine host resources and environment.

Project Kensho OVF Tool 64-bit Installation

This section provides special installation instructions for the Project Kensho OVF Tool on a 64-bit operating systems.
1.   Execute KenshOVF_x64.msi (Follow the prompts)

2.   Ensure ALL networks are either Private or Domain

3.   Launch PowerShell
4.   Set-executionpolicy remotesigned
5.   Change to the installation directory \Program Files\Citrix\Kensho
6.   .\winrmconfigure.ps1 client unsecure (for HTTP communication)
7.   .\winrmconfigure.ps1 client secure (to add HTTPS communication support for secure hosts) 

Appendix - Packages & File Types

This section describes the three file type and two packaging options the Project Kensho OVF Tool produces and consumes. 

One package type occurs when exporting an OVF based virtual machine; the default output is called an OVF Package.  This is a directory that contains the .ovf and the .vhd file.  The name of the OVF Package directory is the name of the OVF the administrator chooses during export.  Each file type is described below.

• filename.ovf
  An Open Virtualization Format (OVF) file is an XML document describing the virtual appliance and defined by the DMTF.  This file contains the virtual machine guest(s) metadata.  Multiple virtual machine guests can be described in a single OVF.  Project Kensho OVF Tool v1.1 supports the OVF standard version 1.0.0c. The filename is the name provided by the administrator during export.  For example, if the administrator chooses to name the OVF foo then the output would be:  foo.ovf. The name foo also represents the name of the OVF Package directory.

• filename.vhd
  A Virtual Hard Disk (VHD) file is the disk image of the virtual machine.  An exported virtual machine guest may contain many VHD files.  Each VHD represents a virtual disk than when combined with an OVF may represent one or more virtual machines.  The filename is the VM GUID described in XenServer or Hyper-V.  This name should not be changed.  Doing so will cause errors during import.

The other package type is called an OVA Package.  This contains the OVF and VHD in a single uncompressed tape archive (TAR) file.  An administrator creates an OVA Package after exporting an OVF as described above in Figure 11. 

• filename.ova
  Unlike an OVF Package, an Open Virtual Appliance (OVA) package is an OVF and VHD stored as a single file using the TAR format.  It is the distribution medium of a virtual appliance.  The filename of an OVA is the name of the OVF that was exported using the Project Kensho OVF Tool.  For example, if the OVF file name is foo.ovf, the OVA will be foo.ova containing both the OVF and VHD file located in the OVF Package directory.  The Project Kensho OVF Tool v1.1 does not support compression of the OVA file.