Customizing Guest Network Settings for Running Virtual Machines

You can use a method of the VirtualMachineGuestCustomizationManager managed object to apply new settings to the virtual NICs in the guest. The VirtualMachineGuestCustomizationManager uses the guest customization engine designed for instant clone operations to customize the guest while it continues running.

The customization step applies new settings for IP address, DNS server, and gateway server of one or more virtual NICs.
Note: DNS settings can be specific to individual NICs in Windows operating systems. DNS settings are global in a Linux operating system.

The guest customization engine must be installed in the virtual machine before you call this method. See Installing the Guest Customization Engine for instructions.

Customization applies the new guest network settings that you specify in the spec parameter to the VirtualMachineGuestCustomizationManager.CustomizeGuest_Task method. The spec parameter is a data object of type CustomizationSpec, which contains a nicSettingMap property that holds an array that maps MAC address to network settings for one or more virtual NICs in the guest.

There are two ways to use the nicSettingsMap array in the spec parameter. You can do one of the following:
  • Specify each virtual NIC explicitly by its MAC address, in spec.nicSettingMap[i].macAddress, and specify the virtual NIC's new settings in the properties of spec.nicSettingMap[i].adapter.
  • Omit spec.nicSettingMap[i].macAddress for all virtual NICs and specify the new settings for each NIC in PCI bus order.
In addition to virtual NIC settings, you can customize these properties of a virtual machine:
  • You can set the CustomizationSpec.identity property to a data object derived from the type CustomizationIdentitySettings. You must choose a subclass of the type that corresponds to the guest operating system installed in the virtual machine. In the identity object you can specify a new host name, domain name, and system time settings.
  • You can set the CustomizationSpec.globalIPSettings property to a data object of type CustomizationGlobalIPSettings in which you specify DNS settings for all virtual NICs. Use this for Linux guest operating systems.
The CustomizeGuest_Task method supports the following guest operating systems:
  • Red Hat Enterprise Linux 6.8 and higher
  • Red Hat Enterprise Linux 7.4 and higher
  • CentOS 7.4 and higher
  • SUSE 11SP4
  • SUSE 12SP3 and higher
  • Ubuntu 16.04 and higher (LTS distributions)

The toolsd service must be running and available for this customization step.

Note: The CustomizeGuest_Task method is asynchronous, but a critical part of the operation, which uses the customization engine, is synchronous.

You can pipeline the instant clone and customization operations to minimize the time needed to clone a virtual machine.

Note: During an instant clone operation, the toolsd service is briefly offline while it resets connections in the clone. This results in no noticeable delay, but you might need to allow for a retry if you run pre-customization code.

The customization data is stored in the Namespace database in a cust.cfg format containing name-value pairs. This makes the customization process resilient to vMotion operations. It also means that you can access the data if needed as input for user-supplied customization scripts.