Configuring a Virtual Machine

You can configure a virtual machine during creation (Folder.CreateVM_Task) or cloning (VirtualMachine.CloneVM_Task). You can also reconfigure a virtual machine using VirtualMachine.ReconfigVM_Task. However, do not use the VirtualMachine.ReconfigVM_Task call to create or add a disk.

In vSphere 5.5 and later, the ReconfigVM_Task method will throw an error when it attempts to change certain virtual machine properties while the virtual machine is powered on. In previous releases, the Server would modify the properties in the configuration specification and the changes would take effect after the virtual machine resets, reboots, or performs a fast suspend and resume.

Since vSphere 5.5, a reconfigure operation modifies the virtual machine in real time, so that the virtual machine properties have been changed by the time the method returns control to the client.

You cannot reconfigure a virtual machine successfully if you specify any of the following properties in the VirtualMachineConfigSpec when you call the ReconfigVM_Task method.

 

Property	VirtualMachineConfigSpec Path
VirtualDevice.unitNumber	deviceChange.device.unitNumber
VirtualDevicePciBuslSlotInfo.pciSlotNumber	deviceChange.device.slotInfo.pciSlotNumber
VirtualDiskFlatVer1BackingInfo.diskMode VirtualDiskFlatVer2BackingInfo.diskMode VirtualDiskRawDiskMappingVer1BackingInfo.diskMode VirtualDiskSeSparseBackingInfo.diskMode VirtualDiskSparseVer1BackingInfo.diskMode VirtualDiskSparseVer2BackingInfo.diskMode	deviceChange.device.backing.diskMode
VirtualDiskFlatVer2BackingInfo.digestEnabled VirtualDiskSeSparseBackingInfo.digestEnabled	deviceChange.device.backing.digestEnabled
VirtualMachineConfigSpec.changeTrackingEnabled	changeTrackingEnabled
VirtualEthernetCard.addressType	deviceChange.device.addressType
VirtualEthernetCard.macAddress	deviceChange.device.macAddress
VirtualEthernetCard.wakeOnLanEnabled	deviceChange.device.wakeOnLanEnabled
VirtualSCSIController.sharedBus	deviceChange.device.sharedBus
VirtualSerialPort.yieldOnPoll	deviceChange.device.yieldOnPoll
VirtualUSBController.autoConnectDevices VirtualUSBXHCIController.autoConnectDevices	deviceChange.device.autoConnectDevices
VirtualUSBController.ehciEnabled	deviceChange.device.ehciEnabled
VirtualMachineVideoCard.useAutoDetect	deviceChange.device.useAutoDetect
VirtualMachineVideoCard.videoRamSizeInKB	deviceChange.device.videoRamSizeInKB
VirtualMachineVideoCard.numDisplays	deviceChange.device.numDisplays
VirtualMachineVideoCard.use3dRendererSupported	deviceChange.device.use3dRendererSupported

The API reference lists all properties and includes information about required permissions for these configuration methods. The following sections describe some commonly specified attributes.

Name and Location

You can specify the display name for the virtual machine by setting the VirtualMachineConfigSpec.name property. Any % (percent) character used in this name parameter must be escaped, unless it is used to start an escape sequence. Clients can also escape any other characters in this name parameter.

Use the annotation field to provide a description of the virtual machine. To remove an existing description, specify the empty string as the value of annotation.

The location of the virtual machine is determined implicitly during creation because you call a Folder.CreateVM_Task method and specify resource pool and optional target host the virtual machine should belong to. See Resource Management Objects for a discussion of resource pools and virtual machine location.

Hardware Version

The hardware version of a virtual machine indicates the lower-level virtual hardware features a virtual machine supports, such as BIOS, number of virtual slots, maximum number of CPUs, maximum memory configuration, and other hardware characteristics.

For a newly created virtual machine, the default hardware version is the most recent version available on the host where the virtual machine is created. To increase compatibility, you might want to create a virtual machine with a hardware version older than the highest supported version. You can do so by specifying the VirtualMachineConfigSpec.version property during virtual machine creation. For existing virtual machines, call the VirtualMachine.UpgradeVM_Task method.

The hardware version of a virtual machine can be lower than the highest version supported by the ESX/ESXi host it is running on under the following conditions:

■	You migrate a virtual machine created on an ESX/ESXi 3.x or earlier host to an ESX/ESXi 4.x host.

■	You create a virtual machine on an ESX 4.x host using an existing virtual disk that was created on an ESX/ESXi 3.x or earlier host.

■	You add a virtual disk created on an ESX/ESXi 3.x or earlier host to a virtual machine created on an ESX/ESXi 4.x host.

Virtual machines with hardware versions lower than 4 can run on ESX/ESXi 4.x hosts but have reduced performance and capabilities. In particular, you cannot add or remove virtual devices on virtual machines with hardware versions lower than 4 when they reside on an ESX/ESXi 4.x host. To make full use of these virtual machines, upgrade the virtual hardware.

Boot Options

You can control a virtual machine’s boot behavior by setting the VirtualMachineConfigSpec.bootOptions property. The VirtualMachineBootOptions data object in that property allows you to specify the following properties:

■	bootDelay – Delay before starting the boot sequence, in milliseconds.

■	bootRetryDelay – Delay before a boot retry, in milliseconds. This property is only considered if the bootRetryEnabled property is set to true.

■	bootRetryEnabled – If set to true, a virtual machine that fails to boot tries again after the bootRetryDelay time period has elapsed.

■	enterBIOSSetup – If set to true, the virtual machine enters BIOS setup the next time it boots. The virtual machine resets this flag to false so subsequent boots proceed normally.

Operating System

The guest operating system that you specify affects the supported devices and available number of virtual CPUs. You specify the guest operating system in the following two properties:

■	guestosid – Specify one of the constants in the VirtualMachineGuestOsIdentifier as a string.

■	alternateGuestName – Full name for the guest operating system. Use this property if guestosid is one of the values of VirtualMachineGuestOsIdentifier starting with other*.

CPU and Memory Information

The VirtualMachineConfigSpec data object allows you to specify CPU and memory configuration.

CPU and Memory Resource Allocation

To allocate resources, use the cpuAllocation and memoryAllocation properties of VirtualMachineConfigSpec. Both properties contain ResourceAllocationInfo objects with the following properties:

■	reservation – Amount of resources that is guaranteed to be available to the virtual machine. If resource utilization is less than the reservation, other running virtual machines can use the resources.

■

limit – Upper limit for CPU or memory resources assigned to this virtual machine. The virtual machine does not exceed this limit, even if resources are available. This property is typically used to ensure consistent performance. If end users are used to work on a virtual machine that uses extra resources, and additional virtual machines are added to the host or resource pool, the virtual machine might slow down noticably. If set to -1, no fixed upper limit on resource usage has been set.

■	shares – Metric for allocating memory or processing capacity among multiple virtual machines. The SharesInfo data object has two properties, level and shares.

■	level – Choose high, low, or normal to map to a predetermined set of numeric values for shares. See the API Reference Guide for the numbers for CPU, memory, and disk shares. Set this property to custom to specify an explicit number of shares instead.

■	shares – Allows you to specify the number of shares you want to allocate to the resource pool. The allocation is divided evenly between resource pools with the same level.

Resource Allocation discusses resource allocation in the context of resource pool hierarchies. The Resource Management Guide includes a detailed discussion of resource allocation in the vSphere environment.

CPU and Memory Modification for Running Virtual Machines

Set CpuHotAddEnabled and CpuHotRemoveEnabled to specify whether virtual processors can be added to or removed from a virtual machine while the virtual machine is running. Set MemoryHotAddEnabled to specify whether memory can be added while the virtual machine is running.

Number of CPUs

You can set the number of virtual processors for the virtual machine with the VirtualMachineConfigSpec.numCPUs property. Legal values for this property change depending on the guestosid value you specify.

CPU Processors and Memory Affinity

If your virtual machine is on an ESX/ESXi system, and if you have a license that supports Symmetric Multiprocessors (SMP), you can configure the virtual machine to have multiple virtual CPUs by setting cpuAffinity and memoryAffinity. You define a set of integers that represents the processors (for CPU) and NUMA nodes (for memory). If you are reconfiguring the affinity setting and leave the array empty, any existing affinity is removed. See the Resource Management Guide for a discussion of NUMA nodes and affinity.

CPU Features

You can use the VirtualMachineConfigSpec.cpuFeatureMask[].info property to represent the CPU features requirements for a virtual machine or guest operating system. See the HostCpuIdInfo data object discussion in the API Reference for a detailed discussion.

Networks

You configure network settings so that a virtual machine can communicate with the host and with other virtual machines.

Virtual Network Interfaces

You can add a virtual network interface to a virtual machine using a subclass of VirtualEthernetCard, you can set the addressType to Manual, Generated, or Assigned. If you choose Assigned, you can specify a MAC address explicitly. See Adding Devices to Virtual Machines.

The number of virtual network interfaces depends on the hardware version you specify for a virtual machine. Hardware version 7 virtual machines support up to ten virtual NICs. Hardware version 4 virtual machines support up to four virtual NICs.

Virtual Machine MAC Address

Upon virtual machine creation, ESX/ESXi or vCenter Server systems assign each virtual network interface its own unique MAC address. The first three bytes of the MAC address that is generated for each virtual network adapter consists of a manufacturer-specific Organizationally Unique Identifier (OUI). The MAC address-generation algorithm produces the other three bytes. vSphere generates MAC addresses that are checked for conflicts. After the MAC address has been generated, it does not change unless the virtual machine is moved to a different location.

All MAC addresses that have been assigned to virtual network interfaces of running and suspended virtual machines on a given physical machine are tracked. The MAC address of a powered off virtual machine is not checked against those of running or suspended virtual machines. It is possible that a virtual machine acquires a different MAC address after a move.

The ESXi Configuration Guide discusses virtual machine MAC addresses in detail.

Fibre Channel NPIV Settings

N-port ID virtualization (NPIV) supports sharing a single physical FC HBA port among multiple virtual ports, each with unique identifiers. This capability lets you control virtual machine access to LUNs on a per-virtual machine basis.

Each virtual port is identified by a pair of world wide names (WWNs): a world wide port name (WWPN) and a world wide node name (WWNN). These WWNs are assigned by vCenter Server. For detailed information on how to configure NPIV for a virtual machine, see the Fibre Channel SAN Configuration Guide.

NPIV support is subject to the following limitations:

■	NPIV must be enabled on the SAN switch. Contact switch vendors for information about enabling NPIV on their devices.

■	NPIV is supported only for virtual machines with RDM disks. Virtual machines with regular virtual disks continue to use the WWNs of the host’s physical HBAs.

■	Virtual machines on a host have access to a LUN using their NPIV WWNs if the physical HBAs on the ESX/ESXi host have access to a LUN using its WWNs. Ensure that access is provided to both the host and the virtual machines

You can set up NPIV with the VirtualMachineConfigSpec properties that start with npiv.

File Locations

File locations for a virtual machine are specified in the following properties:

■	VirtualMachineConfigSpec.files is a VirtualMachineFileInfo data object that allows you to specify the log directory, snapshot directory, suspend directory, and configuration file location. Most locations have a default that you can change as needed.

■

VirtualMachineConfigSpec.locationID is a 128-bit hash based on the virtual machine’s configuration file location and the UUID of the host the virtual machine is assigned to. This property is not usually set by developers; however, clearing this property by setting it to an empty string is recommended if you move the virtual machine.

If a virtual machine’s VirtualMachineCapability.swapPlacementSupported property is true for a virtual machine, you can specify a value for the VirtualMachineConfigSpec.swapPlacement property. The value must be one of the values of the VirtualMachineConfigInfoSwapPlacementType enumeration, as a string.