Home > Blogs > VMware vApp Developer Blog

Self-Configuration and the OVF Environment

The OVF support in vSphere is not just about deployment and packaging. There is also a runtime part, namely the OVF environment. In this post, we will show a simple example on how the OVF environment can be used, by creating a VM template where you can customize its IP address.
Consider the case where you deploy a VM from an OVF package or VM Template. We often want it to be customized just a little bit. A typical customization is IP settings (IP address, netmask, gateway, DNS, etc.), but also application-level settings, such as the location of the SNMP servers, admin logins, etc. Wouldn't it be nice to have a flexible, extensible, open-ended mechanism for doing this? This is exactly what the OVF environment is for.
One way to think of the OVF environment is that the OVF environment is to a VM what the UNIX environment is to a UNIX process. So what does this mean? Well, the UNIX environment is a pretty simple mechanism that stores key/value pairs. These key/value pairs are typically used to tell a process or shell script about the particular environment it is being executed in. The UNIX environment has solved this problem nicely for processes, and the OVF team has been inspired by that feature and created the OVF properties and OVF environment and made it part of the Open Virtualization Format 1.0 specification.

OVF properties are typically configured by the deployer of a vApp, but can also be provided dynamically by vCenter. An example of a dynamic property is the vCenter server IP address. We will look into dynamic properties in a later post.
To illustrate how to use the OVF environment, let us create a self-configuring VM template that configures its IP settings at startup. This is done by using OVF properties to convey information from vCenter to the VM, and installing a boot script in the VM that uses the information to (self) configure the guest software.
Assuming that we have already installed the operating system into the VM, we need to perform the following steps: 

  • Define OVF properties on the VM.
  • Setup the OVF environment transport to carry the settings into the virtual machine.
  • Write some glue code to access and apply the information inside the VM.   

In the video below, we show how this is done using the vSphere client. In our example, we will create properties needed for IP configuration: IP, netmask, gateway, preferred DNS server, and alternate DNS server.
When vCenter powers on a VM in a vApp, or a VM with vApp settings enabled, it creates an XML document called the OVF environment. The OVF environment contains all properties and their values. It is made available to the guest, allowing the guest to apply the properties to its configuration. When the VM is powered on, the OVF environment can also be viewed in the vSphere Client.
The OVF environment can be transported to the guest in two ways:

  • As a CD-ROM containing the XML document. The CD-ROM is mounted on the guests CD-ROM drive.
  • Through VMware Tools. The variable guestinfo.ovfEnv contains the XML document.

In our example, the OVF environment will look like this:

<Environment oe:id=""
xmlns="http://schemas.dmtf.org/ovf/environment/1"
xmlns:oe="http://schemas.dmtf.org/ovf/environment/1"
xmlns:ve="http://www.vmware.com/schema/ovfenv"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<PlatformSection>
<Kind>VMware ESX</Kind>
<Version>4.0.0</Version>
<Vendor>VMware, Inc.</Vendor>
<Locale>en</Locale>
</PlatformSection>
<ve:EthernetAdapterSection>
<ve:Adapter ve:mac="00:50:56:a0:3f:71" ve:network="VM Network"/>
</ve:EthernetAdapterSection>
<PropertySection>
<Property oe:key="dns1" oe:value="10.20.60.1"/>
<Property oe:key="dns2" oe:value="10.20.60.2"/>
<Property oe:key="gateway" oe:value="10.20.63.253"/>
<Property oe:key="ip" oe:value="10.20.63.219"/>
<Property oe:key="netmask" oe:value="255.255.254.0"/>
</PropertySection>
</Environment>

The OVF environment must be read by some "glue" code in the guest – typically upon power-on. It is the responsibility of this code to configure the guest. In our example, we wrote a small Python script. It reads the property values from the XML file on the CD-ROM and configures the IP stack in the guest using netsh.exe: setupIp.py
This script is called from a Windows scheduled task that is executed upon system startup. For Linux, a similar script can be added to /etc/init.d (depending on the Linux distribution).
To access the OVF environment using VMware Tools instead of using the CD-ROM, we could execute the command:
Windows: "C:\Program Files\VMware\VMware Tools\VMwareService.exe" -cmd "info-get guestinfo.ovfEnv"

Linux: vmware-guestd –cmd 'info-get guestinfo.ovfEnv'


In contrast to the normal VC template customization, there is a bit of extra setup required by the author of the template when using the OVF environment. The author is responsible for installing (and possibly writing) the glue code in the guest. However, you get complete freedom in which parameters you can customize, OS independence, and the deployment step is faster and more light-weight.
In our example, we require the user to type in a fixed IP address and have detailed knowledge of various networking parameters. To improve this, we can use dynamic OVF properties to refer to vCenter's IP pools. We will look into this in a future blog post and also how you can share a self-customizing VM template using an OVF package.




Self-Configuration and the OVF Environment

The OVF support in vSphere is not just about deployment and packaging. There is also a runtime part, namely the OVF environment. In this post, we will show a simple example on how the OVF environment can be used, by creating a VM template where you can customize its IP address.
Consider the case where you deploy a VM from an OVF package or VM Template. We often want it to be customized just a little bit. A typical customization is IP settings (IP address, netmask, gateway, DNS, etc.), but also application-level settings, such as the location of the SNMP servers, admin logins, etc. Wouldn't it be nice to have a flexible, extensible, open-ended mechanism for doing this? This is exactly what the OVF environment is for.
One way to think of the OVF environment is that the OVF environment is to a VM what the UNIX environment is to a UNIX process. So what does this mean? Well, the UNIX environment is a pretty simple mechanism that stores key/value pairs. These key/value pairs are typically used to tell a process or shell script about the particular environment it is being executed in. The UNIX environment has solved this problem nicely for processes, and the OVF team has been inspired by that feature and created the OVF properties and OVF environment and made it part of the Open Virtualization Format 1.0 specification.

OVF properties are typically configured by the deployer of a vApp, but can also be provided dynamically by vCenter. An example of a dynamic property is the vCenter server IP address. We will look into dynamic properties in a later post.
To illustrate how to use the OVF environment, let us create a self-configuring VM template that configures its IP settings at startup. This is done by using OVF properties to convey information from vCenter to the VM, and installing a boot script in the VM that uses the information to (self) configure the guest software.
Assuming that we have already installed the operating system into the VM, we need to perform the following steps: 

  • Define OVF properties on the VM.
  • Setup the OVF environment transport to carry the settings into the virtual machine.
  • Write some glue code to access and apply the information inside the VM.   

In the video below, we show how this is done using the vSphere client. In our example, we will create properties needed for IP configuration: IP, netmask, gateway, preferred DNS server, and alternate DNS server.
When vCenter powers on a VM in a vApp, or a VM with vApp settings enabled, it creates an XML document called the OVF environment. The OVF environment contains all properties and their values. It is made available to the guest, allowing the guest to apply the properties to its configuration. When the VM is powered on, the OVF environment can also be viewed in the vSphere Client.
The OVF environment can be transported to the guest in two ways:

  • As a CD-ROM containing the XML document. The CD-ROM is mounted on the guests CD-ROM drive.
  • Through VMware Tools. The variable guestinfo.ovfEnv contains the XML document.

In our example, the OVF environment will look like this:

<Environment oe:id=""
xmlns="http://schemas.dmtf.org/ovf/environment/1"
xmlns:oe="http://schemas.dmtf.org/ovf/environment/1"
xmlns:ve="http://www.vmware.com/schema/ovfenv"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<PlatformSection>
<Kind>VMware ESX</Kind>
<Version>4.0.0</Version>
<Vendor>VMware, Inc.</Vendor>
<Locale>en</Locale>
</PlatformSection>
<ve:EthernetAdapterSection>
<ve:Adapter ve:mac="00:50:56:a0:3f:71" ve:network="VM Network"/>
</ve:EthernetAdapterSection>
<PropertySection>
<Property oe:key="dns1" oe:value="10.20.60.1"/>
<Property oe:key="dns2" oe:value="10.20.60.2"/>
<Property oe:key="gateway" oe:value="10.20.63.253"/>
<Property oe:key="ip" oe:value="10.20.63.219"/>
<Property oe:key="netmask" oe:value="255.255.254.0"/>
</PropertySection>
</Environment>

The OVF environment must be read by some "glue" code in the guest – typically upon power-on. It is the responsibility of this code to configure the guest. In our example, we wrote a small Python script. It reads the property values from the XML file on the CD-ROM and configures the IP stack in the guest using netsh.exe: setupIp.py
This script is called from a Windows scheduled task that is executed upon system startup. For Linux, a similar script can be added to /etc/init.d (depending on the Linux distribution).
To access the OVF environment using VMware Tools instead of using the CD-ROM, we could execute the command:
Windows: "C:\Program Files\VMware\VMware Tools\VMwareService.exe" -cmd "info-get guestinfo.ovfEnv"

Linux: vmware-guestd –cmd 'info-get guestinfo.ovfEnv'


In contrast to the normal VC template customization, there is a bit of extra setup required by the author of the template when using the OVF environment. The author is responsible for installing (and possibly writing) the glue code in the guest. However, you get complete freedom in which parameters you can customize, OS independence, and the deployment step is faster and more light-weight.
In our example, we require the user to type in a fixed IP address and have detailed knowledge of various networking parameters. To improve this, we can use dynamic OVF properties to refer to vCenter's IP pools. We will look into this in a future blog post and also how you can share a self-customizing VM template using an OVF package.


12 thoughts on “Self-Configuration and the OVF Environment

  1. Mike Laverick

    This is great. But, this .py format is phython script, right? And windows (as far as I know – has no idea of what python is. Could you should the scheduled task that actually, causes this script to be triggered, and how do you make .py files execute?

  2. Martin Amdisen

    Yes, the .py file is a Python script. So in this example I did the following:
    1. Download Python from http://www.python.org/ to my Windows VM and put the path to python.exe in the PATH environment variable.
    2. Create a batch file, e.g. named setupIp.bat with a single line:
    python “C:\boot\setupIp.py”
    3. Add a scheduled task that points to the batch file.

  3. Dikang Gu

    To access the OVF environment using VMware Tools instead of using the CD-ROM on Linux, I think we should execute the following command:
    vmware-guestd –cmd “info-get guestinfo.ovfEnv”

  4. Javier

    Good morning,
    I would like to know if someone have the same py script for linux?
    Best Regards,

  5. Javier

    Another question. How can execute on Linux the script the fist time when boot
    linux? This script is not on the OS so is necesary to put in ovf file or start in vmware-tools.
    Best Regads,

  6. D

    I am using vSphere 4.1. But i am not able to see vApp option in options tab. Could you please let me know if i missed any setting in my client

  7. Martin Amdisen

    If you log in to a vCenter Server, vApp options should be available. They are not available if you are using the client to manage a stand-alone ESX host.
    The dialog for editing settings on a VM always contains a tab called Options. This tab has a setting called vApp Options. These may be enabled or disabled, and can only be edited on the VM when they are enabled.

Comments are closed.